HTTPS verbs can be used to differentiate requests and tell the server what you want out of your request. It can also impose restrictions that can allow a more structured and secure web application. Using HTTP verbs can allow you to separate creating, updating, modifying, and deleting resources on the server and/or database. Keep in mind, that these rules are not set in stone when you control or create a web server you don’t have to follow these rules and you can do whatever you want with these verbs. Implementing strict rules when using HTTP verbs is often referred to as restful or restful development.
In this post, I will not cover how to implement a server or create a database. I will cover the basics of the different HTTP verbs and what they are used for, this should be treated as a starter or beginning read when exploring this topic. Do not treat this information as gospel, there are many different ways to use these verbs and no one way is the ‘correct’ way of using them.
The GET verb is used to retrieve a resource from the server. For example, getting a customer or user by their id value or name. The GET verb shouldn’t be used to add or update any information on the server. It should be a read-only operation. Another thing to note about the GET verb is that there shouldn’t be a body to the request, the entire request should be contained within the URI.
For example, you could send a GET request to the following URL ‘/users/’ and send a JSON object with the id contained. Although, the ‘proper’ way to do this would be to send a GET request to ‘/users/2’ (to get the user with the id of 2). Then if you send a request to ‘/users/’ without an id value the server would return all the users, or at least the first page of users.
The POST verb is used for creation endpoints. An HTTP request with this verb is used to create a new resource on the server. For example, you sending a POST request to the ‘/users/’ URI with a JSON body containing the information about a new user. This will then create a new user on the server/database. A thing to keep in mind with this request verb is that is the resource already exists an error should be thrown, instead of just replacing or merging the existing and newly sent objects. An object already exists if the id of the sent object matches an existing object – or if you have a unique username policy, or unique email policy.
The PUT verb is used to update an existing resource with new values, this is a replace operation. Similarly to the POST verb you would send a request to the ‘/users/’ endpoint with a body containing the information of the object. Instead of throwing an error if the object exists it will replace the existing object with the newly sent object. However, it should throw an error if the object doesn’t already exist, as a replace operation cannot be successful if there is no object to be replaced.
The DELETE verb, like with the GET verb, tells you what it does from its name. This is used for delete operation. The request structure is similar to a GET request, you don’t include a body and include the id (or unique identifier) in the URI, e.g. ‘/users/1’. This will then delete the specified user. This should throw an error if the user doesn’t exist, as you cannot delete something that doesn’t exist. You could have a delete all operation happen if you sent a request to ‘/users/’ without any specific id, but this could be dangerous as it could result in an accidental deletion of a lot of data. So I would advise keeping the deleting to a single object (or a single object and it’s children) instead of allowing multiple deletions of the same object type in one operation.
The PATCH verb is similar to the POST verb. It is used to update an existing resource. However, instead of replacing the existing resource it will only update the sent values. For example, if you send a request to the ‘/user/1’ endpoint with just a new name field then only the name will be updated and the rest of the fields will be kept the same. If you did this same thing with a POST verb then everything in the object would be replaced with nothing apart from the new name. It is a modification vs replacement.
Those are the differences between the HTTP verbs in a restful context. However, this is not a mandatory structure. All of the requests detailed in this post could be achieved just by using the POST verb. However, a great reason to follow this structure or a similar structure, is that a request to the same URI can exist if the verbs differ. For example, you cannot have two different POST request handlers for the ‘/user/’ URI but you could have two if the HTTP verb was different per request.