Using HTTP Verbs for REST APIs made Easy

Introduction

Action Verbs are core to RESTful architecture. An action verb defines what action the client wants to perform on the server resource. It is a mutually agreed upon channel that the server accepts to perform. Even when you are constructing a HTTP request from your client you will provide the Action Verb as the HttpMethod before sending the request.

In general, you use the following 5 HTTP Action Verbs while creating a request.

HTTP GET

We use this to fetch data from a resource. A GET request doesn’t require anybody to pass, and the response would be the current state of the resource requested. Any filtering criteria is passed via the query string, or through the headers.

Some limitations of HTTP GET?

• HTTP GET represents a retrieval operation from a resource, with optional arguments or filters.
• It can’t be used to send large data to the server.
• All the data that is sent via HTTP GET is attached to the resource URL which is of limited length (255 chars max)
• HTTP GET should only be used to fetch data
• To send complex data over HTTP GET we can use decorators over the parameters in the controller action to which the request is being made. This is again framework dependent.

HTTP POST

We use this to submit some data to a resource. This is often used to submit a new entity to the resource, which is not yet present. It is passed via the request body. The response is optional, but could be a primitive result (created Id) or a complex type (an object).

HTTP PUT

We use this to submit some data to a resource. This is similar to HTTP POST in usage. The main difference between a POST and a PUT request is that –

A POST request creates a new entity to the resource. A PUT request replaces the existing entity with a new state of the entity

We generally pass the resourceId in the request path, while in some designs we have the same request path as that of a HTTP POST, but the payload contains the resourceId.

HTTP PATCH

We use this to submit some data to a resource. This action verb is used when you want to change one or more attributes of the current state of a resource. Similar to a PUT request, we generally pass the resourceId in the request path, while in some designs we may pass it via the payload.

People often use HTTP POST, PUT and PATCH requests interchangeably because they all look alike. But from a best practice, use HTTP POST when you are creating a new entity, use HTTP PATCH when you wish to change one or two properties of that entity and HTTP PUT when you replace that record entirely with a new version.

Differences between HttpPost HttpPut and HttpPatch methods

HTTP POST	HTTP PATCH	HTTP PUT
when you are creating a new entity which doesn’t exist before	when you wish to change one or two properties of existing entity	when you wish to replace a record entirely with a new version
No filtering criteria needed	The existing record Identifier is to be passed	The existing record Identifier is to be passed
Response can be the created resource Identifier or an object	Response can be the updated resource Identifier or an object	Response can be the updated resource Identifier or an object

HTTP DELETE

We use this to delete an entity from the resource. This request doesn’t have any request payload and the resourceId which is to be deleted is passed via the request path. There is often a confusion between when to use HTTP GET and HTTP DELETE.

A HTTP DELETE action can’t be called over the browsers directly – It can only be called over an XHRHttpRequest.

Calling a HTTP DELETE action over a browser by means of the resource URL results in 405 (Method Not Allowed) by the server.

But from a best practice and readability perspective – use HTTP GET when you are fetching a resource and HTTP DELETE when you wish to delete it. There is a response expected from this action.

What are the differences between HttpGet and HttpDelete?

HTTP GET	HTTP DELETE
use when you wish to fetch an existing resource from the server	when you wish to delete an existing resource from the server
the request doesn’t contain any body, identifier is sent via request path	the request doesn’t contain any body, identifier is sent via request path
the response may contain the requested data	no response may be returned since the record now doesn’t exist
Can be called directly from a browser window	Cannot be called directly, only via XmlHttpRequest. It results in 405 (Method not allowed)

Apart from these, there are 2 more HTTP actions that are performed by the client without our notice as preliminary or precursor steps.

HTTP OPTIONS

A HTTP OPTIONS request has no request body. It returns the permitted communication options for a given URL or server. Using this action, a client can find out if the server supports an operation or get all the operations the server supports overall. When you use any client application in the browser, every API call is preceded by an OPTIONS call by the client http libraries to check if those options work or not. This is also known as a preflight request, that happens in the case of CORS.

HTTP HEAD

A HTTP HEAD request too has no request body. This request also doesn’t have any response. Then why is it for? A HTTP HEAD request returns all the response headers returned by a resource path. The idea is to use this when you wish to know the information sent via headers that are sent by the server when a resource is requested. For example, a client can know the download size via the content-length of a response before it calls to download a very large file from the server.

There are two more methods that are used for miscellaneous purposes

HTTP TRACE

A HTTP TRACE method, if supported by the server, can be used to perform a message loop-back test along the path to the target resource, providing a useful debugging mechanism. For example, you may wish to debug or troubleshoot if a request is working or not. In such cases it can be helpful. The request has no body, nor the response has any content.

HTTP CONNECT

A HTTP CONNECT method opens a tunnel between the client and server. It can be used to start a two-way communication. General applications can include websocket communications and SSL based connections.

Conclusion

HTTP Action Verbs are used to communicate to the server the intended operation requested by the client. There are sevaral action verbs available in the RESTful architecture that help in performing CRUD operations. Also there are other action verbs which happen under the hood or to be used to troubleshoot.

We discussed the following 9 action verbs used in making REST API calls –

• HTTP GET
• HTTP POST
• HTTP PUT
• HTTP PATCH
• HTTP DELETE
• HTTP HEAD
• HTTP OPTIONS
• HTTP TRACE
• HTTP CONNECT

I hope this article gives you simple understanding of these action verbs and where they are used. Please do share it with your friends if you find it useful!