RESTful API 设计:更新 (PUT) 中的不可更改数据应该是可选的吗? [英] RESTful API design: should unchangable data in an update (PUT) be optional?

问题描述

我正在实施 RESTful API，我不确定社区接受"行为是否存在无法更改的数据.例如，在我的 API 中有一个文件"资源，它在创建时包含许多创建后无法修改的字段，例如文件的二进制数据，以及一些与之关联的元数据.此外，文件"可以有书面描述和相关标签.

I'm in the middle of implementing a RESTful API, and I am unsure about the 'community accepted' behavior for the presence of data that can not change. For example, in my API there is a 'file' resource that when created contains a number of fields that can not be modified after creation, such as the file's binary data, and some metadata associated with it. Additionally, the 'file' can have a written description, and tags associated.

我的问题涉及更新这些文件"资源之一.特定文件"的 GET 将返回所有元数据、描述和与文件关联的标签，以及文件的二进制数据.特定文件"资源的 PUT 是否应包含只读"字段?我意识到它可以用任何一种方式编码:a) 在 PUT 数据中包含只读字段，然后验证它们与原始字段匹配(或发出错误)，或 b) 忽略 PUT 数据中只读字段的存在因为它们无法更改，如果它们不匹配或由于逻辑忽略它们而丢失，则永远不会发出错误.

My question concerns doing an update to one of these 'file' resources. A GET of a specific 'file' will return all the metadata, description & tags associated with the file, plus the file's binary data. Should a PUT of a specific 'file' resource include the 'read only' fields? I realize that it can be coded either way: a) include the read only fields in the PUT data and then verify they match the original (or issue an error), or b) ignore the presence of the read only fields in the PUT data because they can't change, never issuing an error if they don't match or are missing because the logic ignores them.

似乎可以采用任何一种方式并且可以接受.第二种忽略只读字段的方法可以更紧凑，因为 API 客户端可以根据需要跳过发送只读数据；这对于知道自己在做什么的人来说似乎很好...

Seems like it could go either way and be acceptable. The second method of ignoring the read only fields can be more compact, because the API client can skip sending that read only data if they want; which seems good for people who know what they are doing...

推荐答案

除非只读数据占数据的很大一部分(极端情况下，传输只读数据对网络流量和响应时间)，您应该编写服务以接受 PUT 中的只读字段并检查它们的更改.让相同的数据进出更简单.

Unless the read-only data makes up a significant portion of the data (to the extreme that transmitting the read-only data has a noticeable impact on network traffic and response times), you should write the service to accept the read only fields in the PUT and check them for changes. It's just simpler to have the same data going in and out.

这样看:您可以在 PUT 中包含可选的只读字段，但您仍然必须/应该在服务中编写代码以检查收到的任何只读字段是否包含预期的值.无论哪种方式，您都必须编写只读检查.

Look at it this way: You could make inclusion of the read only fields optional in the PUT, but you will still have to / should write the code in the service to check that any read only fields that were received contain the expected values. You have to write the read only checking either way.

禁止 PUT 中的只读字段是一个坏主意，因为这将要求客户端删除他们在 GET 中从您那里收到的字段.这要求客户比他们真正需要的更密切地参与您的数据和语义.客户会认为这是一个令人头疼的问题，一个不必要的并发症，并且你会增加他们的负担.获取从您的 GET 接收到的数据，修改一个感兴趣的字段，然后用 PUT 将其发送回您，对于客户端来说应该是一个脑残的简单往返.不必要的时候不要把事情复杂化.

Prohibiting the read-only fields in the PUT is a bad idea because it will require the clients to strip away fields they received from you in the GET. This requires that the client get more intimately involved with your data and semantics than they really need to be. The clients will consider this a headache, an unnecessary complication, and downright mean of you to add to their burden. Taking data received from your GET, modifying one field of interest, and sending it back to you with a PUT should be a brain-dead simple round-trip for the client. Don't complicate things when you don't have to.

这篇关于RESTful API 设计:更新 (PUT) 中的不可更改数据应该是可选的吗?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！