I spent some time this evening assembling a response to a Stackoverflow question:
My answer:
(Note:2025-04-06 Sunday: Addendum, at bottom)
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
- 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
Interesting API Update Examples
Okta
2025-04-06 Sunday: Addendums
https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Resources_and_specifications
RFC 9110: HTTP Semantics
See: section 9.3.3
https://www.rfc-editor.org/rfc/rfc9110.html#POST
- "The
POST method requests that the target resource process the
representation enclosed in the request according to the resource's own
specific semantics"
- "An origin server
indicates response semantics by choosing an appropriate status code
depending on the result of processing the POST request"
Also see:
RFC 9113: HTTP/2
https://www.rfc-editor.org/rfc/rfc9113
RFC 9114: HTTP/3
https://www.rfc-editor.org/rfc/rfc9114
