REST API-带有实际示例的PUT与PATCH

本文翻译自：REST API - PUT vs PATCH with real life examples

First of all, some definitions: 首先，一些定义：

PUT is defined in Section 9.6 RFC 2616 : PUT在9.6节RFC 2616中定义：

The PUT method requests that the enclosed entity be stored under the supplied Request-URI. PUT方法请求将封闭的实体存储在提供的Request-URI下。 If the Request-URI refers to an already existing resource, the enclosed entity SHOULD be considered as a modified version of the one residing on the origin server . 如果Request-URI引用了已经存在的资源， 则应将封闭的实体视为驻留在源服务器上的实体的修改版本 。 If the Request-URI does not point to an existing resource, and that URI is capable of being defined as a new resource by the requesting user agent, the origin server can create the resource with that URI. 如果Request-URI没有指向现有资源，并且请求用户代理能够将该URI定义为新资源，则原始服务器可以使用该URI创建资源。

PATCH is defined in RFC 5789 : PATCH在RFC 5789中定义：

The PATCH method requests that a set of changes described in the request entity be applied to the resource identified by the Request- URI. PATCH方法请求将在请求实体中描述的一组更改应用于由Request-URI标识的资源。

Also according to RFC 2616 Section 9.1.2 PUT is Idempotent while PATCH is not. 同样根据RFC 2616，第9.1.2节 PUT是幂等的，而PATCH不是。

Now lets take a look at a real example. 现在让我们看一个真实的例子。 When I do POST to /users with the data {username: 'skwee357', email: 'skwee357@domain.com'} and the server is capable of creating a resource, it will respond with 201 and resource location (lets assume /users/1 ) and any next call to GET /users/1 will return {id: 1, username: 'skwee357', email: 'skwee357@domain.com'} . 当我使用数据{username: 'skwee357', email: 'skwee357@domain.com'}对/users进行POST并且服务器能够创建资源时，它将响应201和资源位置（假设/users/1 ）和对GET /users/1下一次调用将返回{id: 1, username: 'skwee357', email: 'skwee357@domain.com'} 。

Now lets say I want to modify my email. 现在说我要修改我的电子邮件。 Email modification is considered "a set of changes" and therefor I should PATCH /users/1 with " patch document ". 电子邮件修改被视为“一组更改”，因此，我应该使用“ 补丁文档 ”来修补 /users/1 。 In my case it would be a json {email: 'skwee357@newdomain.com'} . 在我的情况下，它将是json {email: 'skwee357@newdomain.com'} 。 The server then returns 200 (assuming permission are ok). 然后，服务器返回200（假设允许）。 This brings me to first question: 这使我想到第一个问题：

• PATCH is NOT idempotent. 补丁不是幂等的。 It said so in RFC 2616 and RFC 5789. However if I'll issue the same PATCH request (with my new email) Ill get the same resource state (with my email being modified to the requested value). 它在RFC 2616和RFC 5789中是这样说的。但是，如果我发出相同的PATCH请求（使用我的新电子邮件），则会得到相同的资源状态（将我的电子邮件修改为请求的值）。 Why isn't PATCH then idempotent? 为什么PATCH不那么幂等？

PATCH is a relatively new verb (RFC introduced in March 2010), and it comes to solve the problem of "patching" or modifying a set of fields. PATCH是一个相对较新的动词（2010年3月引入RFC），用于解决“修补”或修改一组字段的问题。 Before PATCH was introduced, everybody used PUT to update resource. 在引入PATCH之前，每个人都使用PUT来更新资源。 But after PATCH was introduced, it leaves me confused what is PUT used for then? 但是在引入PATCH之后，让我感到困惑的是，PUT是用来做什么的？ And this brings me to second (and the main) question: 这使我想到了第二个（也是主要的）问题：

• Whats the real difference between PUT and PATCH? PUT和PATCH之间的真正区别是什么？ I've read somewhere the PUT might be used to replace entire entity under specific resource, so one should send the full entity (instead of set of attributes as with PATCH). 我读过某处PUT可能会用来替换特定资源下的整个实体，因此应该发送完整的实体（而不是像PATCH那样发送一组属性）。 What is the real practical usage for such case? 这种情况的实际实际用途是什么？ When would you like to replace / overwrite an entity under specific resource URI and why such operation is not considered as updating / patching the entity? 您何时要替换/覆盖特定资源URI下的实体，为什么不将这种操作视为更新/修补实体？ The only practical use case I see for PUT is issuing a PUT on collection, ie /users to replace the entire collection. 我在PUT上看到的唯一实际用例是在集合上发布PUT，即/users替换整个集合。 Issuing PUT on a specific entity makes no sense after PATCH was introduced. 引入PATCH之后，在特定实体上发布PUT毫无意义。 Am I wrong? 我错了吗？

---

#1楼

参考：https://stackoom.com/question/1vPas/REST-API-带有实际示例的PUT与PATCH

---

#2楼

I was curious about this as well and found a few interesting articles. 我也对此感到很好奇，并发现了一些有趣的文章。 I may not answer your question to its full extent, but this at least provides some more information. 我可能不会完全回答您的问题，但这至少提供了更多信息。

http://restful-api-design.readthedocs.org/en/latest/methods.html http://restful-api-design.readthedocs.org/en/latest/methods.html

The HTTP RFC specifies that PUT must take a full new resource representation as the request entity. 在HTTP RFC规定PUT必须为请求实体焕发出新的资源表示。 This means that if for example only certain attributes are provided, those should be remove (ie set to null). 这意味着，例如，如果仅提供某些属性，则应将其删除（即设置为null）。

Given that, then a PUT should send the entire object. 鉴于此，那么PUT应该发送整个对象。 For instance, 例如，

/users/1
PUT {id: 1, username: 'skwee357', email: 'newemail@domain.com'}

This would effectively update the email. 这将有效地更新电子邮件。 The reason PUT may not be too effective is that your only really modifying one field and including the username is kind of useless. PUT可能不太有效的原因是，您真正真正修改的一个字段并包括用户名是没有用的。 The next e