While designing our APIs, we often need to make a decision, which method do we’d like to choose to create a new resource on the server.
Will it be POST or PUT?
But hey, wait a minute, there’s still a PATCH method. Will it be suitable for this purpose?
In this short text, I’m going to go through all these methods and show you what are the best use cases for each of them.
PUT
Take a look at the RFC for the reference:
The PUT method requests that the enclosed entity be stored under the
supplied Request-URI.If the Request-URI refers to an already existing resource, the enclosed entity should be considered as amodified version of the one residing on the origin server.
If the Request-URI does not point to an existing resource, and that URI is capable of being defined as a new resource by the requesting user
agent, the origin server can create the resource with that URI.
In short:
- Use it for new resources creation or for the resource update. It means the replacement of the entire existing resource.
- Not a safe method.
- Idempotent – the result should be always the same.
POST
Again, let’s take a look at the specs and what it says about the POST method:
The POST method is used to request that the origin server accept the entity enclosed in the request as a new subordinate of the resource
identified by the Request-URI in the Request-Line.
In short:
- Use it for adding new resources into the existing collection of resources.
- Not a safe method.
- Not idempotent – the resource status won’t be the same after using it multiple times. Which means it can result in creating multiple resources.
PATCH
The PATCH method is very handy but it’s not always been here. It has been introduced in 2010 and is used very widely in the modern APIs.
Take a look at the excerpt from the official description of this method (from RFC5789):
The PATCH method is similar to PUT except that the entity contains a list of differences between the original version of the resource identified by the Request-URI and the desired content of the resource after the PATCH action has been applied.
In short:
- Use it for updating the resource partially.
- Not a safe method.
- It can be idempotent.
POST vs PUT vs PATCH – a job offer example
Let’s wrap it up in the story to make it more understandable.
So let’s assume we’re looking for the new superstar remote developer to join our team.
We’d like to use the GitHub Jobs platform as our job board of choice.
Time to POST the offer
So let’s assume we’d like to use the nice web API of GitHub Jobs, where we’d like to publish the offer. Literally, we’d like to ‘post‘ the offer, so naturally, we’ll use the POST method.
So we send the following request:
POST https://jobs.github.com/positions
If everything is okay, we should get the response with 200 (OK) code and the following resource in the response body:
Voila! Our wonderful job offer has been posted 🚀
Let’s PUT the replacement
But things are changing fast, especially in our industry.
They told you instead of full-stack dev, we need someone with deep expertise in the JVM-based languages.
But instead of posting the new offer, we’re going to replace the entire existing offer. We’d like to replace the offer entirely.
PUT https://jobs.github.com/positions/remotePositionUid
According to the HTTP specs, we should expect a response with 200 (OK) code. The response body should contain the updated job offer.
Send salary PATCH to the offer
Let’s assume we’d to increase the salary budget for that position 💰.
In other words: we’d need the method which allows us to update the resource partially. The PATCH method will be the most suitable here.
PATCH https://jobs.github.com/positions/remotePositionUid
And that’s it. You may expect the entire job offer object in the response (it depends on the headers you sent) with 200 (OK) code.
So, for example, you should expect to get something like this:
Now, with such an offer, I bet you’ll find a good candidate for this position👍