2020-11-20 Friday - REST API Design Guidance (PUT, POST, or PATCH for update?)

Photo by Ryan Quintal on Unsplash

I spent some time this evening assembling a response to a Stackoverflow question:

"How should I design a REST API?"
https://stackoverflow.com/questions/64940600/how-should-i-design-a-rest-api/64940695#64940695

My answer:

Reading the RFCs is highly recommended

RFC 7231 Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content

https://tools.ietf.org/html/rfc7231

In particular, pay close attention to Section 4.3 Method Definitions

https://tools.ietf.org/html/rfc7231#section-4.3

• "The POST method requests that the target resource process the representation enclosed in the request according to the resource's own specific semantics."

• "The PUT method requests that the state of the target resource be created or replaced with the state defined by the representation enclosed in the request message payload."

Which is to say - that you will find variation in how an update action is processed (some folks use POST, some use PATCH, many use PUT), depending on their implementation-specific resource semantics.

In your example, it appears that the PUT resource-specific semantic implementation is treating the submitted data element as a full replacement - and since you did not include the age element - it is left as null.

PATCH is indeed intended as the verb for doing a partial update, refer to:

RFC 5789 PATCH Method for HTTP

https://tools.ietf.org/html/rfc5789

• "The PATCH method requests that a set of changes described in the request entity be applied to the resource identified by the Request-URI. The set of changes is represented in a format called a "patch document" identified by a media type."

• "The difference between the PUT and PATCH requests is reflected in the way the server processes the enclosed entity to modify the resource identified by the Request-URI. In a PUT request, the enclosed entity is considered to be a modified version of the resource stored on the origin server, and the client is requesting that the stored version be replaced. With PATCH, however, the enclosed entity contains a set of instructions describing how a resource currently residing on the origin server should be modified to produce a new version. The PATCH method affects the resource identified by the Request-URI, and it also MAY have side effects on other resources; i.e., new resources may be created, or existing ones modified, by the application of a PATCH."

• "PATCH is neither safe nor idempotent"

• "There is no guarantee that a resource can be modified with PATCH. Further, it is expected that different patch document formats will be appropriate for different types of resources and that no single format will be appropriate for all types of resources. Therefore, there is no single default patch document format that implementations are required to support."

• "Clients need to choose when to use PATCH rather than PUT. For example, if the patch document size is larger than the size of the new resource data that would be used in a PUT, then it might make sense to use PUT instead of PATCH. A comparison to POST is even more difficult, because POST is used in widely varying ways and can encompass PUT and PATCH-like operations if the server chooses. If the operation does not modify the resource identified by the Request-URI in a predictable way, POST should be considered instead of PATCH or PUT."

When using PATCH for JSON type documents, see

RFC 6909 - JavaScript Object Notation (JSON) Patch

https://tools.ietf.org/html/rfc6902

• "JSON Patch defines a JSON document structure for expressing a sequence of operations to apply to a JavaScript Object Notation (JSON) document; it is suitable for use with the HTTP PATCH method. The "application/json-patch+json" media type is used to identify such patch documents."

Additionally, you may find these resources useful

1. https://restfulapi.net/http-methods/
2. https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods
3. https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PATCH
4. https://en.wikipedia.org/wiki/Patch_verb
5. http://jsonpatch.com/
6. https://microservices.io/book

 

Interesting API Update Examples 

Okta

• https://developer.okta.com/docs/reference/api/authorization-servers/ 
• https://developer.okta.com/docs/reference/api/users/#update-user
  
• "Use the POST method to make a partial update and the PUT method to delete unspecified properties."
• "Updates a user's profile and/or credentials using strict-update semantics"
• "All profile properties must be specified when updating a user's profile with a PUT method. Any property not specified in the request is deleted."
  
• "Important: Don't use PUT method for partial updates."