Rest Architecture and Http Verbs
Let’s learn Http verbs with sticky notes
Yazının Türkçe versiyonuna bu link ile ulaşabilirsiniz.
I wrote an article previously about Rest architecture and the rules of Rest architecture. In this article, I will focus on the most common http verbs in web services that are developed according to the Rest architecture and in which situations they should be used.
As I mentioned in my previous article, resource is an important concept in Rest architecture. Resources are represented by nouns. To access resources, we use endpoints where the name of the resource is mentioned in the form of http(s)://host/resources. The service provider (server) learns the operations we want to carry out on the resource (for example, generating records, reading records, deleting records or updating records) through http verbs.
We will talk about the meanings of the most frequently used Post, Get, Patch, Put, Delete verbs while writing a service according to the Rest architecture or while using a service prepared according to the Rest architecture.
Imagine writing to-do items on small pieces of paper and hanging it on your wall. I will try to explain verbs over this sample space.
POST
The post verb is used to create a new record in the resource.
You were sitting in your room. Your mother came and asked you to buy milk from the market. In this case, you have a new task. You take a piece of paper and write your task on it and add it to your task list.
GET
The get verb is used to access information without causing any changes in the resource.
As new tasks come, you write them on papers and hang them on your wall. Now it’s time to review your to-do list. Your mother came in and asked for information about task number three. In order to query the data in the source with the identifier, a hierarchical path is usually followed, such as http(s)://host/resource/identifier.
Consider the scenario where your father comes in and asks about your unfinished tasks. In this case, this is more like a question of what the tasks that meet the criteria are, rather than fetching information as in the previous scenario. These criteria take their place at the URI as query-parameters.
PATCH
The patch verb is used to make partial changes to the existing record in the resource.
Imagine that you have completed the task your father gave you. In this case, all you have to do is update the completed status on the task sheet.
PUT
The put verb is used to create a new record in the resource and to update it if there is a record matching the criteria.
Your mother came and asked you to go to the market until tomorrow, to buy 2 bottles of milk and 10 eggs. In this case, you replace the old task sheet with the new task sheet and try to achive the task in its final form.
The main difference between Patch and Put is that one changes part of the record in the focused resource, while the other recreates all the fields in the record.
Let’s continue to explain this verb with another scenario. Your mother is back in your room. She stated that she changed the shopping list, so she brought a new list. Let’s consider the scenario where we see subtasks as a subresource. Pasting the new shopping list on top of the old shopping list is an action we will take by using Put verb. This is because we are completely reshaping the data of a resource.
Let’s say we send a request to the service point “https://host/ademcatamak/tasks/3/subtasks" using the Get verb instead of the Put verb. Now imagine the data you see. We will be making a change on whole data we obtain as a result of this request. For this reason, even if we make a partial change on the task sheet, we should choose Put instead of Patch, since we have changed our entire focus area.
DELETE
The delete verb is used to remove the existing record in the resource.
Let’s imagine the situation where your brother goes to the market and gets your mother’s requested items. Your mother will come and tell you that you don’t have to go to the market anymore. In this case, you can now eliminate your task. If you want, you can tear off the paper (hard delete) or put a cross on the paper (soft delete). When someone asks you about your tasks, it will be considered as a deletion as long as you ignore this record.
When you look at it from the client’s perspective, the actions taken on the resource determine which verb you should choose. If an action means updating from the server’s perspective (IsDeleted = true) and means deletion from the client’s perspective, the verb you should be choosing is Delete.
I hope it has been a useful post. You can click on this link to browse my other articles.
