HTTP VERBS

As REST architecture is based on HTTP protocol rules, the verb of the request is used to add semantic value to the action. Also, we must follow the protocol guidelines on the use of the different verbs.

GET

Retrieve a representation of a resource or list of resources. GET, as HEAD or PUT, is an idempotent verb, which means that making multiple identical requests ends up having the same result as a single request. Requests with GET can be also considered safe when used only to read data (can be called without risk of data modification or corruption). GET requests should return an HTTP code 200 OK when successfully.

POST

Is used for creating new resources. POST is neither safe nor idempotent (making two identical POST requests should result in two resources with the same data). On successful call, should return an HTTP code 201, returning also a Location header with a link to the newly-created resource.

PUT

Should be used for update resources by sending a PUT request to a known resource URI, with the request body containing the newly-updated representation of the original resource. PUT can also be used to create a resource in the case where the resource identifier is chosen by the client instead of by the server (this is achieved with a PUT request to the URI that contains the value of a non-existing resource identifier, or the URI of the future resource once created). This last method is generally considered a little tricky or confusing and is not widely used.

DELETE

Used to delete the resource specified by the resource URI. Should return an HTTP status 200 OK if successful, with a response body, could be the representation of the deleted item or some message. Sending no response body is also acceptable, but in this case the status returned code should be HTTP 204 (No content). DELETE operations should be idempotent. When you DELETE a resource, it’s removed, and subsequents calls to DELETE for that resource will no produce any different result. Calling DELETE on a resource a second time will often return an HTTP code 404 (Not found) since it’s no longer available. This makes DELETE operations no longer idempotent, but is an appropriate compromise if resources are removed from the database instead of being simply marked as deleted.

PATCH

PATCH is a method that is not safe, nor idempotent, and allows full and partial updates and side-effects on other resources. This method let us to update only some attribute of a resource (i.e., a flag) without sending the entire object again.