CODEWITHSUNDEEP
resthttp
John Winston
John Winston

Reputation: 1471

Should I implement both PUT and PATCH route?

I am trying to learn the difference between PUT and PATCH. If I need to create a route for updating a resource, for example User, should I implement both PUT and PATCH?

If I can partially update a resource with PATCH, why would I want to use PUT?

Upvotes: 0

Views: 826

Answers (1)

VoiceOfUnreason
VoiceOfUnreason

Reputation: 57194

I am trying to learn the difference between PUT and PATCH.

Start from "how are they the same?"

PUT and PATCH are both used in a remote authoring context; we use those message semantics to tell the server to make its own representation of some resource look like our local copy.

For instance, if I wanted to change the title of the home page of my website, I could

GET /home.html

to load the current version into my HTML editor. I could then make my changes to my local copy. To release my changes, I send a message to the server "make your copy like my copy".

With PUT, the payload of the request is a complete copy of my version of the document. I send the whole document back to the server to be processed.

With PATCH, I create a "patch document", which is to say a representation of my changes using some media type that the server understands. The server is expected to compute the new representation for itself, by applying the patch document to its local copy.

PUT has idempotent semantics; what this means is that general purpose components, like web browsers and reverse proxies, know that multiple copies of the same request received in succession means the same thing as a single copy of that request. That means that, in the event of a network failure where the request or response may have been lost, we can automatically resend the request.

PATCH does not promise idempotent handling -- even if the patch-document describes an idempotent change to the resource, general purpose components are not going to know that the request is safe to resend.

On the other hand, if your document is larger (relative to the size of the HTTP headers) and your changes are small, then a patch document will be smaller than the complete representation; if the network is sufficiently reliable, smaller requests can have better investment odds than repeatable requests.

Your most flexible play, of course, is to support both, and also describe both methods, and the media-types of the patch formats that you support, in the response to an OPTIONS request. That allows the client to choose the appropriate method based on their own local context.

PATCH requires more compatibility than PUT, because the client and the server need to both understand the same patch media type (in addition to understanding the media type of the representation itself).

So you are probably better off with PUT, and then supplementing it with PATCH as alternative in conditions where the client needs to optimize, rather than the reverse.

If you are doing something very specific, then the general guidelines may not apply.

For instance, if you are implementing a JSON:API, intended for JSON:API clients, then you are going to want to use PATCH, because JSON:API has a rather peculiar position on the use of PUT, and application/vnd.api+json specifies how to use it as a patch document. So the concern about the client and server understanding the same patch representations "goes away".

Upvotes: 3

Related Questions