Difference between POST vs PUT vs PATCH

Con­fused whether to use PUT or PATCH or POST in your API? Don’t wor­ry you are not alone and this is a com­mon con­fu­sion which hap­pens to most of us or to all of us at some point while devel­op­ing our API. Before we under­stand the dif­fer­ence between PUT vs PATCH vs POST, first we need to under­stand Idempotency.

What is Idem­po­ten­cy #

Idem­po­tence is the prop­er­ty of cer­tain oper­a­tions in math­e­mat­ics and com­put­er sci­ence, that can be applied mul­ti­ple times with­out chang­ing the result beyond the ini­tial application.

To put the above quote in terms of APIs

To sim­ply put, idem­po­ten­cy can be described as an API call when done mul­ti­ple times pro­vides the same result. For exam­ple, the GET method requests a cer­tain blog post. No mat­ter how many times it is called the same blog post is returned (con­tent can vary) in the same for­mat. While the returned val­ue can vary with updates to the post, the con­tent for­mat is always same.

HTTP request meth­ods or ​‘verbs’ equiv­a­lent to the CRUD, but they are not the same and serve dif­fer­ent purpose

• cre­ate — POST
• read — GET
• update — PUT
• delete — DELETE

Now that we have an idea about idem­po­ten­cy, lets under­stand POST, PUT and PATCH and where does the con­fu­sion arise.

What is POST #

POST is a HTTP method used to cre­ate a new resource in a col­lec­tion of resources. POST method should ide­al­ly be used only to cre­ate new resources. Since REST does­nt have a stan­dard set of rules, some APIs use POST to update a resource as well. This is bet­ter to avoid. Use POST only to cre­ate a resource.

On suc­cess­ful cre­ation, return HTTP sta­tus 201, return­ing a Loca­tion head­er with a link to the new­ly-cre­at­ed resource.

Lets look at this exam­ple: When you POST the fol­low­ing pay­load to the url

HTTP POST  https://programmerspub.com/blog/general

Payload: 

{
	"blog_title": "What is POST",
	"blog_post": "Confused whether to use PUT or PATCH or POST...",
	"blog_post_author": "programmerspub"
}

We get this following response

{
	"blog_post_id": 3
	"blog_title": "What is POST",
	"blog_post": "Confused whether to use PUT or PATCH or POST...",
	"blog_post_author": "programmerspub"
}

If you do the same request 2 times, 2 resources are cre­at­ed. Due to this rea­son, POST methond is not idem­po­tent and unsafe.

{
	"blog_post_id": 4
	"blog_title": "What is POST",
	"blog_post": "Confused whether to use PUT or PATCH or POST...",
	"blog_post_author": "programmerspub"
},
{
	"blog_post_id": 3
	"blog_title": "What is POST",
	"blog_post": "Confused whether to use PUT or PATCH or POST...",
	"blog_post_author": "programmerspub"
}

POST method is non-idem­po­tent and is cacheable.

What is PUT #

PUT is anoth­er HTTP method used to cre­ate a new resource at a spec­i­fied URI or to update an exist­ing resource. Although PUT can be used to cre­ate a resource, it is most often used to update resource. To cre­ate a new resource, using PUT we need to know the exact URI where the data needs to be put. If incase there is data in the spec­i­fied URI, the entire data is over­writ­ten which is update.

To cre­ate a resource at spec­i­fied URI /5:

HTTP PUT  https://programmerspub.com/blog/5

Payload: 

{
	"blog_title": "What is PUT",
	"blog_post": "Confused whether to use PUT or PATCH or POST...",
	"blog_post_author": "programmerspub"
}

To update a resource:

HTTP PUT  https://programmerspub.com/blog/5

Payload: 

{
	"blog_title": "What is PUT",
	"blog_post": "Confused whether to use PUT or PATCH or POST...updated post...",
	"blog_post_author": "programmerspub"
}

Most impor­tant thing to remem­ber is the PUT pay­load should have all the fields of the resource when updat­ing or else the resource is over­writ­ten with the data we send. 

For exam­ple con­sid­er this PUT request where we send only the updat­ed blog title.

HTTP PUT  https://programmerspub.com/blog/general/5

Payload: 

{
	"blog_title": "What is PUT - updated",
	"blog_post": "Confused whether to use PUT or PATCH or POST...updated post...",
	"blog_post_author": "programmerspub"
}

After the PUT request only the blog title has the updat­ed val­ue while blog_​post and blog_​post_​author fields are lost.

{
	"blog_title": "What is PUT - updated"
}

PUT is idem­po­tent and are not cacheable.

What is PATCH: #

PATCH is anoth­er HTTP method which is used to update a resource with par­tial data. Unlike PUT, PATCH does not need the full pay­load to update a resource. For exam­ple if a resource has 100 fields, using PATCH would be a bet­ter option than PUT as PUT requires all 100 fields to be sent again to update a resource.

HTTP PATCH  https://programmerspub.com/blog/general/5

Payload: 

{
	"blog_title": "What is PATCH - updated"
}

After the PATCH request, only the field blog_​title is update while oth­er fields remain intact.

{
	"blog_title": "What is PATCH - updated",
	"blog_post": "Confused whether to use PUT or PATCH or POST...updated post...",
	"blog_post_author": "programmerspub"
}

PATCH is nei­ther safe nor idempotent.

Why does the con­fu­sion arise? #

POST and PUT are both pop­u­lar HTTP meth­ods that are used inter­change­ably as they are both used to cre­ate and update a resource.

How­ev­er, it is impor­tant to under­stand that POST should ide­al­ly be used to cre­ate a resource while PUT is to update a resource. 

POST works on a col­lec­tion while PUT works on a sin­gle resource.

Sum­ma­ry #

So, while design­ning your API, under­stand the HTTP verbs idem­po­ten­cy and your use case to define the cor­rect meth­ods for the API calls.