If you’re still getting the hang of web development and HTTP specification, you might find yourself often confused about which verbs to use and when.
Some developers learn that most applications on the internet are CRUD (Create, Read, Update, Delete) applications and that the HTTP verbs match to these actions 1:1. POST is a Create, GET is a Read, PATCH (or PUT) is an Update, and DELETE is a Delete.
But unfortunately, nothing is that easy - such is life. For instance, a PUT can be used to both create and update a resource. But...if a PUT can create a resource, why would I use POST? And which method is better for updating - PUT or PATCH?
Let’s dive in and discuss five of the most common HTTP verbs and when to use them (GET, POST, PATCH, PUT, and DELETE.)
This blog post is a follow-on to our updated Definitive Guide to API Integration. Download the full guide for more in-depth content on integration best practices, from pre-build to post-build, or check out the blog series.
The History of HTTP Verbs
When the HTTP/1.1 specification was first released in 1999, it established four of the five main HTTP verbs we still use today – GET, POST, PUT, and DELETE.
But it wasn’t until 2010 that RFC 5789 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 you want to both create a resource AND have the server create a URI (Uniform Resource Identifier) for said resource.
For instance, if you wanted to create a new article, you would need to perform a POST to /articles and the article would be created and given a URI (for example, /articles/1234.)
But how do you 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’s an important distinction. The HTTP specification considers PUT to be “idempotent,” while POST is not.
The definition of idempotence: “Methods can 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
Because PUT is idempotent, this means that you can execute the same PUT request with the same data to /articles/1234 infinite times and expect the same result or side effects. If you were to execute a POST to /articles with the same data infinite times, you would get infinite new resources.
Basically, you use POST to create a new resource when you don’t know the URI. You should use PUT to create a new resource when you DO know the URI or if you 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.elements@cloud-elements.com", "favorite_color": "blue" }
If you wanted to update the favorite_color attribute via a PUT, you would need to send an entire representation of the resource and just change the favorite_color. For this example object it’s no big deal, but for larger, more complicated objects or resources it can be tedious. With a PATCH, you could simply send the following JSON to update the favorite color:
{ "favorite_color": "red" }
Once again, like when 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 almost certainly use HTTP and its 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.
Ready to learn more about best practices for building an API integration? Check out our Definitive Guide to API Integration (you might find the “Develop” and “API Design” sections especially useful.)
Even more? Check out the next post in the series: data search and browsing.