HTTP Verbs Demystified: PATCH, PUT and POST

By Brad Scharmann in Developer Posted Apr 21, 2015

CRUD Applications

When I was first learning web development and the HTTP specification, I often found myself overwhelmingly confused about which verbs to use and when. I had it explained to me that most applications on the internet are CRUD (Create, Read, Update, Delete) applications and that the HTTP verbs match to these actions 1 to 1. POST is a Create, GET is a Read, PATCH (or PUT) is an Update, and DELETE is a, well, Delete. 

HTTP Verbs: Patch, Put and Post

But as often is the case in life, things are not always as they seem, nor are they simple. A PUT can be used to both create and update a resource. As soon as I heard this it was as if everything I had ever known evaporated. If a PUT can create a resource, why do I use POST? Which is better for updating, PUT or PATCH? It’s time to dive into the HTTP specification and find out what is really going on.

(For the purposes of this blog we will be focusing on 5 HTTP verbs – GET, POST, PATCH, PUT and DELETE. There are several other HTTP verbs as well which are far less common.)

When the HTTP/1.1 specification was first released in 1999 it established 4 of the 5 main HTTP verbs we still use today – GET, POST, PUT and DELETE (http://tools.ietf.org/html/rfc2616). It wasn’t until 11 years later in 2010 that RFC 5789 (http://tools.ietf.org/html/rfc5789) introduced the PATCH verb as a way of partially updating a resource. So before we even start to think about PATCH, what’s the difference between PUT and POST? A POST is used when we both want to create a resource AND have the server create a URI (Uniform Resource Identifier) for said resource.

For instance, if we wanted to create a new article we would perform a POST to /articles, and our article would be created and given a URI, for example – /articles/1234. So how do we create a resource via PUT? When using put, we expect to already KNOW the URI of the resource. So if I perform a PUT to /articles/1234 and it does not already exist, it will create that resource for me at that URI. I can also perform a PUT to /articles/1234 if it DOES exist, and it will update the resource. It may seem like a minor difference, but it is an important distinction. The HTTP specification considers PUT to be “idempotent” while POST is not. Here is the definition of idempotence from the HTTP specification-

“Methods can also have the property of “idempotence” in that (aside from error or expiration issues) the side-effects of N > 0 identical requests is the same as for a single request. The methods GET, HEAD, PUT and DELETE share this property…”

JSON OBJECT EXAMPLES:

What this means is that I can execute the same PUT request with the same data to /articles/1234 infinite times and expect the same result or side effects. If I execute a POST to /articles with the same data infinite times, I will get infinite new resources (thus POST is NOT idempotent). So I use POST to create a new resource where I don’t know the URI. I use PUT to create a new resource where I DO know the URI or if I want to update a resource. So why introduce PATCH? PATCH was introduced for partial resource updating. Let’s take the following JSON object example for a user:

{ "first_name": "Claude", "last_name": "Elements", "email":

"claude@cloud-elements.com", "favorite_color": "blue" }

If I wanted to update the favorite_color attribute via a PUT I would have to send an entire representation of the resource and just change the favorite_color. For our example object this is no big deal, but for larger more complicated objects or resources this can be tedious. With a PATCH I can merely send the following JSON:

{ "favorite_color": "red" }

And it will simply update the favorite color. Once again, like with comparing POST and PUT, this is a very subtle but important distinction.

When designing your next RESTful API or building your next web application, you will most likely use HTTP and thus it’s associated verbs. Selecting the right verbs is an important part of that process. The more we all understand and follow the specifications, the better our experience will be when integrating and building cooperative apps.

Read some previous post in this series: 

Or check out our API Resource Center for guides, infographics, webinars and white papers covering API integration and management:

Visit Resource Center