Just like we have simple methods for your smart device, we have standard methods for a REST API. A huge amount of effort has been simplified when the HTTP methods were defined for specific purposes. For any API which is built, they need to use these methods only. And nobody can use any custom methods to make the API ecosystem more complex. If these are too simple, then why there is a need to discuss about them? we can just have a list and use them in our APIs. Well, the answer is yes. But there are different situations where you might stuck your head in which method to be used? then this blog will come to your rescue.
Need of having HTTP Verbs in an API design
Just like we have verbs in English, so that nobody can come up with a verb of his own. and when anyone from any country is speaking in English, the verb he wants to communicate is the same verb as perceived by the user. Ever heard that somebody is saying that “he is singing” when actually the other person is running? or vice versa (well the vice versa may be true if he is running and singing!). But this is the kind of discipline that we follow in our daily lives. Same decision we need to translate when we are making the API design.
When an API built by a developer of Japan has the HTTP method as GET, it means that the API resource is for retrieving something. No other developer in the world will think it as an API to create something? (until you are asking this to a 3 year old kid of yours). Same goes for the other HTTP methods defined by REST.
API Methods analogy to the CRUD operations
Did it strike your mind that the HTTP methods in your API are actually based on the CRUD operations? When they were made initially, it was to satisfy all the CRUD operations. Later on the support for some specific functionalities was added to cater to more specific purposes.
| Create | POST |
| Read | GET |
| Update | PUT |
| Delete | DELETE |
The CRUD operations are more readable than the REST operations other than the GET and DELETE operations. The reason being that we need to actually include the method as part of the request unlike the CRUD operation. So, it is having as minimal letters as possible. Let’s understand each method in the next section.
Different methods in a REST API (Explained by use-case)
We will understand the methods by including a practical use case rather than ranting the theory.
Use Case – Jason is having a book store and he wants to automate the process of the database. Whenever a new book arrives, he is manually creating an object in the database. And he runs a query whenever he wants to retrieve information about any book. In this case, he has decided to follow an API to do these tasks. So that in future, he can automate these tasks without much of a manual intervention.
POST – This method is used when a user wants to create something. For example, Jason will use this method whenever he wants to make an entry of a new book. So, he will simply use a POST method, give some parameters like the book name, author name, paperback, publisher etc & create a new entry in the database.
GET – This method is very literal and not require much information. But still we need to understand how powerful get method is. When Jason wants to retrieve information about any book he will use the GET method, which is the most common use case. But there are other use cases of a GET method that I will discuss in detail in a different blogpost.
DELETE – This method will be used to delete an entity, that entity can be a singular entity or can be a JSON object. Usually in the API world, it is an object. For example, information about a book needs to be deleted when it is no longer relevant in the book store.
PUT – When there are few attributes of an entity that needs to be modified or updated, we use the PUT method. This method will retain the object as a whole, but will update the requested attributes.
PATCH – PATCH method is used for updation of a fraction of the whole object. For example you have an e-book named “Wings of Birds” and the publisher is “Ostrich Communications”. Suppose the publisher has re-branded itself as “Ostrich Media”. The other attributes like the book name, book published date will remain same, but the publisher will change, so you will use the PATCH method instead of a PUT method. But, this method is optional so whether you should use a PATCH method or not? Find out here https://apigraphy.home.blog/2020/04/03/put-vs-patch-difference/
OPTIONS – An options method is used to indicate the requester about what all methods he can actually use for a particular URL. For instance, a /books with OPTIONS method might return like this.
curl -X OPTIONS http://example.org -i
The response then contains an Allow header with the allowed methods:
HTTP/1.1 204 No Content
Allow: OPTIONS, GET, HEAD, POST
Cache-Control: max-age=604800
Date: Thu, 13 Oct 2016 11:45:00 GMT
Expires: Thu, 20 Oct 2016 11:45:00 GMT
Server: EOS (lax004/2813)
x-ec-custom-error: 1
The another significance of using an OPTIONS method is in a pre flight request for a CORS request. This is because the Pre-flight request will tell the requester on what is allowed to be sent. For example “Access-Control-Allowed-Headers” will send a list of headers allowed. In literal meaning which translates as ” the options of headers that can be used for this request”, hence the name of the HTTP verb.
HEAD – This method is the least used method among all. The return is similar to that of a GET method, but it necessarily doesn’t contain any body. The metainformation contained in the HTTP headers in response to a HEAD request SHOULD be identical to the information sent in response to a GET request. This method can be used for obtaining metainformation about the entity implied by the request without transferring the entity-body itself. This method is often used for testing hypertext links for validity, accessibility, and recent modification.
I wish this was helpful in making you decide about the HTTP method to be used in your API design. Feel free to post any queries below or any topic on which you would like to have a blog to be published.
APIgeeek 