Use HTTP PATCH Method
The HTTP PATCH method is used to make modifications to existing resources. In particular, it is designed for "partial updates", as opposed to replacing an entire resource using the HTTP PUT method. Although certain HTTP PATCH requests may behave idempotently, this is not true of all possible PATCH requests, so this request method is not idempotent, nor considered safe. The request body of a PATCH request may be simple application/json, or a more specialized type, such as application/json-patch+json.
[00:00] The HTTP PATCH method is used to make changes to existing resources. Let's take a look at making a PATCH request to update the title of a GitHub issue I've already created.
[00:11] Here we're going to see that the PATCH method is used in our request. Like POST, PATCH requests include a message body. There's a content-type header to indicate the type of our content, as well as the actual request body.
[00:26] We can see that the GitHub server has responded with a 200 family status code, indicating the PATCH was successful. When we take a look at the details, we can, in fact, see that the issue's title has been updated. That is the essence of the HTTP PATCH method -- take an existing resource and modify some of the values therein.
[00:46] Much like POST, HTTP PATCH requests cannot be considered idempotent. Let's take a look at why. In the GitHub API, the way you can update the labels for an issue is to issue a request where we completely replace all of the labels assigned to the issue.
[01:05] We can certainly see that issuing this request several times would have the exact same effect as issuing the request one time. All of the labels will be replaced with the specified labels on request.
[01:16] If we imagine that the GitHub API wanted to allow users to add a label without destroying or replacing any of the other labels that may be assigned to this issue, we can imagine that the GitHub API might use a JSON PATCH request to do this.
[01:34] Let's take a look at how that might look. Our request includes one operation with the intent to add a new label into the label array. This would have the effect of whatever is in the existing labels, adding one more label to the WONTFIX label.
[01:48] This sort of request would not have the same effect if issued multiple times. We would theoretically have duplicate labels in our labels array. These sort of possible changes that are not idempotent are the reason that PATCH itself in general is not considered idempotent. Proxies and other libraries will not attempt to retry these requests if there's a problem such as network errors.
[02:14] To summarize, HTTP PATCH is used to make modifications to existing resources. There are several available content types that can be used to perform those actions.