我应该如何设计 REST API？

Question

I am making a REST API with spring framework. Then, I was worried, so I started posting.

When there is data as below,

GET /users/1

{
   "name": "mike",
   "age": 21
}

Currently, REST API has been developed as follows.

PUT /users/1

{
   "name": "mike"
}

When requested by PUT as above, the name is changed and the missing attribute age becomes null as follows.

GET /users/1

{
   "name": "mike2",
   "age": null
}

---

PATCH /users/1

{
   "name": "mike2"
}

When requesting PATCH as above, the name is changed and the missing attribute age is not changed as follows.

GET /users/1

{
   "name": "mike2",
   "age": 21
}

I want to know if this fits the REST API rules.

If this isn't appropriate, how do I request if I want to modify name and delete age in one request?

I need help.

Answer 1

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, see:

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; ie, 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."

For JSON 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

https://restfulapi.net/http-methods/

https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods

https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/PATCH

https://en.wikipedia.org/wiki/Patch_verb

http://jsonpatch.com/

https://microservices.io/book