Since we will be dealing with URLs over HTTP and will be using HTTP methods, it is better to spend some time understanding the nature of HTTP methods.
We should also understand that HTTP methods are not actually doing any type of listing or creation or modification by themselves. It is just a convention to use certain HTTP methods and URL patterns for certain operations. These methods do not perform any operations on their own but it depends on the server-side developer. These methods can result in any operation depending on the code that the developer writes.
When we talk about the nature of HTTP methods, then it is about the convention and standards which are followed. After all, RESTful web services are about preferring convention over configuration. The foundation of today's HTTP and REST lies on these conventions and while writing RESTful web services, we are going to follow these conventions.
HTTP methods can be both safe or unsafe. By safe, it means the methods not expected to any resource on the server and by unsafe it means the are expected to change resource on the server. So this way, we have GET
as the only safe method, as it is not expected to change anything on the server while other methods such as PUT
, POST
, PATCH
, and DELETE
are considered as unsafe methods since they are expected to do some changes on the server.
There are methods which achieve the same results matter how many time repeat the same operations. We consider GET
, PUT
, PATCH
, and DELETE
as idempotent methods, as no matter how many times we repeat these method calls, it will always result in the same thing. For example, if you are using GET example.com/books
, it will always return the same list of books, no matter how many times you call this URL with the GET
method. However, if user put something else in database then it can have different result in listing but to declare some method idempotent or not, we are not considering change in result because of external factors instead of that method call itself. In the same way, if you use PUT
or PATCH
, let's say PATCH
example.com/books/2?author=Ali
, it will always result in the same response no matter how many times you call this method with the same parameters.
The same is the case with DELETE
. It doesn't matter many times you call DELETE
on the resource, it will only be deleted once. However, for DELETE
, it can vary based on the implementation as well. It is something that depends on how you as a programmer want to implement. You probably want to DELETE
and give a successful response the first time and on subsequent calls. You can simply give 404 because the resource no longer exists.
POST
is non-idempotent because it creates a new resource on the server and the response has at least one unique attribute (mostly that is the ID of the resource), even if all the other attributes are same in the case of the same request parameters.
Until now, we have understood RESTful web services conventions, URL patterns, HTTP methods, and the nature of HTTP methods. However, it was mostly about requests. The URL and HTTP method are both request-related points. We haven't yet looked at responses, so now let's take a look into that.