HTTP Methods and why you should be using them on your API

Every single one of us has, even if without knowing, used the protocol before. Otherwise, I wouldn’t have written this on Medium and, therefore, you wouldn’t be reading it. HTTP When writing ’s one should ensure that it uses the standard methods. These are a great pillar to build a stable and, very important, scalable . , , … which one should I use? My answer to that is: depends on what you want to do! REST API HTTP API GET POST PUT When should I use each method? The main verbs, or methods if you prefer to call them that, are: HTTP GET POST PUT / PATCH DELETE You may be like: “Hey thanks, I didn’t know about that! But… when am I supposed to use each one of them?” Let me explain them to you (and hopefully don’t make this too boring)! GET If you check the specification of the protocol it says, and I quote: HTTP/1.1 “The GET method means retrieve whatever information (in the form of an entity) is identified by the Request-URI. If the Request-URI refers to a data-producing process, it is the produced data which shall be returned as the entity in the response and not the source text of the process, unless that text happens to be the output of the process.”. Simplifying this is to say that the verb (or method) should be used to retrieve the information you’re looking for. Take the following : GET URL https://api-url.dev/api/v1/users/1 It should retrieve all the accessible information about the user with the . ID 1 POST Let us check the specification of the protocol yet again. It says: HTTP/1.1 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. POST is designed to allow a uniform method to cover the following functions: - Annotation of existing resources; - Posting a message to a bulletin board, newsgroup, mailing list, or similar group of articles; - Providing a block of data, such as the result of submitting a form, to a data-handling process; - Extending a database through an append operation. Well, these are a lot of words to say that the verb to store information on the server. POST Take the following URL: https://api-url.dev/api/v1/users This should be used to create a new user. You can send all the required information (username, password, etc.) using the body of the request you’re going to make. HTTP PUT / PATCH Let us check the protocol one more time. What does it say about verb? HTTP/1.1 PUT 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 a modified version of the one residing on the origin server. In other words, the text above is telling us that we should use the verb to update an existing resource, say, for instance, an existing user. PUT Using the URL: https://api-url.dev/api/v1/users/1 The system should update the information regarding user with the with the information sent in the request. ID 1 But… what about the verb? PATCH Right! The verb. Say, for instance, that you want to update the user with the , like the example right above, but you just want to send just the newly updated field, let’s say the password field. In this case, you should use the verb. Why? Because you’re just sending a fragment of the user entity, which in this example is the password, thus this verb is adequate as you’re ing the given user. PATCH ID 1 PATCH PATCH DELETE Ah, the last but not the least: the verb. So, checking the specification one last time (finally no?) we get the following: DELETE The DELETE method requests that the origin server delete the resource identified by the Request-URI. This method MAY be overridden by human intervention (or other means) on the origin server. The client cannot be guaranteed that the operation has been carried out, even if the status code returned from the origin server indicates that the action has been completed successfully. However, the server SHOULD NOT indicate success unless, at the time the response is given, it intends to delete the resource or move it to an inaccessible location. Deciphering the slightly confusing text it says that you should be using the verb every time that you want to remove some resource from the server. DELETE If you execute a request on the following: DELETE https://api-url.dev/api/v1/users/1 The server should delete the user with the and, perhaps, all the resources associated with him. ID 1 And that’s it! I’ve covered up everything I’ve proposed at the beginning of the article. Hope that you enjoyed the reading and let me know if you have any question or suggestion to improve. Cheers,