Rest Service Http Method
HTTP is the protocol that allows for sending documents back and forth on the web. A protocol is a set of rules that determines which messages can be exchanged, and which
messages are appropriate replies to others. In HTTP, there are two different roles: server and client. In general, the client always initiates the conversation; the server
replies. HTTP is text based; that is, messages are essentially bits of text, although the message body can also contain other media. Text usage makes it easy to monitor
an HTTP exchange.
HTTP messages are made of a header and a body. The body can often remain empty; it contains data that you want to transmit over the network, in order to use it according to the instructions in the header. The header contains metadata, such as encoding information; but, in the case of a request, it also contains the important HTTP methods. In the REST style, you will find that header data is often more significant than the body. The table below lists the standard methods that have a well-defined meaning for all resources and collections.
|GET||Retrieve all or single resources in a collection|
|POST||Create a new resource in a collection|
|PUT||Update a resource|
|DELETE||Delete a resource|
|PATCH||Update a resource|
|OPTION||Return available HTTP methods and other options|
|HEAD||Retrieve all or single resources in a collection (header only)|
GET is the simplest type of HTTP request method; the one that browsers use each time you click a link or type a URL into the address bar. It instructs the server to transmit the data identified by the URL to the client. Data should never be modified on the server side as a result of a GET request. In this sense, a GET request is read-only, but of course, once the client receives the data, it is free to do any operation with it on its own side - for instance, format it for display.
POST is used when the processing you wish to happen on the server should be repeated, if the POST request is repeated (that is, they are not idempotent; more on that below). In
addition, POST requests should cause processing of the request body as a subordinate of the URL you are posting to.
In plain words:
should not cause the resource at /clients/, itself, to be modified, but a resource whose URL starts with /clients/. For instance, it could append a new client to the list, with an id generated by the server.
A PUT request is used when you wish to create or update the resource identified by the URL. Unlike the former two requests this is not so widely used. Suppose on client request you are performing some action on the server and the state of the server has to be same in the next requests then you can go for PUT. For ex. When you upload a file for the first time a new file is created in the server and the state of the server has been changed. If you again try to upload the same file the old file has to be replaced by the new one instead of creating another one. Unlike POST, a client can issue this request safely two or more times because the state changed in the server should be same as in the first request. PUT is more linked with the update operation but that has not to be the case always.
As the name the delete method should be used to remove or delete something from the server. For ex. to delete a row from database table or remove a file from file-system etc. Sometimes people wrongly use GET or POST to do that but you are creating a service and want to say it is completely RESTful then you should use DELETE method for that.
When you use a PATCH, you only update the field you specify and leave the rest alone as in your project or example. One final benefit; PATCH is atomic, which means that if
you need to do some complex changes to the state of a resource, you can do it with confidence. It also means that you can create synthetic resources and PATCH them if you
need to orchestrate changes to the state of several resources.
The difference between the PUT and PATCH requests is reflected in the way the server processes the enclosed entity to modify the resource identified by the Request-URI. In a PUT request, the enclosed entity is considered to be a modified version of the resource stored on the origin server, and the client is requesting that the stored version be replaced. With PATCH, however, the enclosed entity contains a set of instructions describing how a resource currently residing on the origin server should be modified to produce a new version. The PATCH method affects the resource identified by the Request-URI, and it also MAY have side effects on other resources; i.e., new resources may be created, or existing ones modified, by the application of a PATCH.
This method is also not widely used. When you are creating a REST service and to return what are the operations that can be performed on a particular resource you should use this method. If a resource is read-only then issuing this request method on that resource returns a response header named Allow with the values GET and HEAD.
This request method is not widely used and it is used to fetch only the response header information from the server. This method is much similar like GET, should not change the state of the server but returns only the metadata information. This HEAD request method can be used to know whether a particular resource exist in the server or not or to know information about the resource. The difference between the GET and HEAD request methods are the former one returns the entity body but the later not.
An idempotent HTTP method is a HTTP method that can be called many times without different outcomes. It would not matter if the method is called only once, or ten times over. The
result should be the same. Again, this only applies to the result, not the resource itself. This still can be manipulated (like an update-timestamp, provided this information
is not shared in the (current) resource representation. Consider the following examples:
Example 1: a = 4;
Example 2: a++;
The first example is idempotent: no matter how many times we execute this statement, a will always be 4. The second example is not idempotent. Executing this 10 times will result in a different outcome as when running 5 times. Since both examples are changing the value of a, both are non-safe methods. In HTTP, safe methods are not expected to cause side effects. Clients can send requests with safe methods without worrying about causing unintended side effects. To provide this guarantee, implement safe methods as read-only operations. Safety does not mean that the server must return the same response every time. It just means that the client can make a request knowing that it is not going to change the state of the resource.
GET, HEAD, PUT and DELETE request methods are idempotent. Idempotent means how many times these requests are applied serially to the server the result is same as the intial request. If you are deleting a resource or data through DELETE request, when you issue the request at the first time the resource is removed from the server and if you again issue the same request nothing new should happen in the server i.e the state of the server should not be changed. The same rule applies for other requests also. When you are designing RESTful services idempotence should also be considered for these HTTP methods.