我正在为客户管理系统编写一个RESTful服务,并试图找到部分更新记录的最佳实践。例如,我希望调用者能够使用GET请求读取完整的记录。但是为了更新它,只允许对记录进行某些操作,比如将状态从ENABLED更改为DISABLED。(我有比这更复杂的场景)

出于安全原因,我不希望调用者只提交更新字段的整个记录(这也感觉有点过分)。

是否有构造uri的推荐方法?在阅读REST书籍时,RPC样式的调用似乎是不受欢迎的。

如果下面的调用返回id为123的客户的完整客户记录

GET /customer/123
<customer>
    {lots of attributes}
    <status>ENABLED</status>
    {even more attributes}
</customer>

我该如何更新状态?

POST /customer/123/status
<status>DISABLED</status>

POST /customer/123/changeStatus
DISABLED

...

更新:扩充问题。如何将“业务逻辑调用”合并到REST api中?有没有大家都同意的做法?并非所有的方法本质上都是CRUD。有些更复杂,如“sendEmailToCustomer(123)”,“mergeCustomers(123, 456)”,“countCustomers()”

POST /customer/123?cmd=sendEmail

POST /cmd/sendEmail?customerId=123

GET /customer/count 

当前回答

你基本上有两个选择:

Use PATCH (but note that you have to define your own media type that specifies what will happen exactly) Use POST to a sub resource and return 303 See Other with the Location header pointing to the main resource. The intention of the 303 is to tell the client: "I have performed your POST and the effect was that some other resource was updated. See Location header for which resource that was." POST/303 is intended for iterative additions to a resources to build up the state of some main resource and it is a perfect fit for partial updates.

其他回答

你基本上有两个选择:

Use PATCH (but note that you have to define your own media type that specifies what will happen exactly) Use POST to a sub resource and return 303 See Other with the Location header pointing to the main resource. The intention of the 303 is to tell the client: "I have performed your POST and the effect was that some other resource was updated. See Location header for which resource that was." POST/303 is intended for iterative additions to a resources to build up the state of some main resource and it is a perfect fit for partial updates.

您应该使用POST进行部分更新。

要更新客户123的字段,需要POST到/customer/123。

如果你只想更新状态,你也可以PUT到/customer/123/status。

通常,GET请求不应该有任何副作用,而PUT用于写入/替换整个资源。

这直接来自HTTP,如这里所示:http://en.wikipedia.org/wiki/HTTP_PUT#Request_methods

你的扩充问题需要补充的东西。我认为您通常可以完美地设计更复杂的业务操作。但你必须放弃方法/过程的思维方式,更多地考虑资源和动词。

邮件发送


POST /customers/123/mails

payload:
{from: x@x.com, subject: "foo", to: y@y.com}

这个资源+ POST的实现将发送邮件。如果有必要,你可以提供类似/customer/123/发件箱这样的东西,然后提供到/customer/mails/{mailId}的资源链接。

客户数

您可以像处理搜索资源一样处理它(包括具有分页和num-found信息的搜索元数据,它可以提供客户的数量)。


GET /customers

response payload:
{numFound: 1234, paging: {self:..., next:..., previous:...} customer: { ...} ....}

关于你的更新。

我认为CRUD的概念在API设计方面造成了一些混乱。CRUD是对数据执行基本操作的一般低级概念,HTTP谓词只是请求方法(创建于21年前),可能映射到CRUD操作,也可能不映射到CRUD操作。事实上,请尝试在HTTP 1.0/1.1规范中找到CRUD首字母缩写。

在谷歌云平台API文档中可以找到一个应用实用约定的解释很好的指南。它描述了创建基于资源的API背后的概念,一个强调大量资源而不是操作的API,并包括您正在描述的用例。虽然这只是他们产品的一种惯例设计,但我认为这很有意义。

这里的基本概念(也是产生很多混淆的概念)是“方法”和HTTP动词之间的映射。一件事是定义API将对哪种类型的资源执行什么“操作”(方法)(例如,获取客户列表或发送电子邮件),另一件事是HTTP动词。您计划使用的方法和动词必须有一个定义,以及它们之间的映射。

它还说,当一个操作与标准方法(在本例中是List、Get、Create、Update、Delete)不完全匹配时,可以使用“自定义方法”,比如BatchGet,它根据多个对象id输入检索多个对象,或者SendEmail。

您应该使用PATCH进行部分更新—使用json补丁文档(参见https://datatracker.ietf.org/doc/html/draft-ietf-appsawg-json-patch-08或http://www.mnot.net/blog/2012/09/05/patch)或XML补丁框架(参见https://www.rfc-editor.org/rfc/rfc5261)。但在我看来,json-patch最适合您的业务数据类型。

带有JSON/XML补丁文档的PATCH对于局部更新具有非常严格的前向语义。如果您开始使用POST,使用原始文档的修改副本,进行部分更新,您很快就会遇到问题,您希望丢失值(或者更准确地说,空值)来表示“忽略此属性”或“将此属性设置为空值”—这导致了一个被破解的解决方案的兔子洞,最终将导致您自己的补丁格式。

你可以在这里找到更深入的答案:http://soabits.blogspot.dk/2013/01/http-put-patch-or-post-partial-updates.html。