Sunday, November 10, 2013

Web API(s) and HTTP Protocols

Having being through many API(s) and code reviews, one thing which comes to front is the invalid use of http methods to perform web api calls. In this article I am going to focus on standard practices of when to use which http method while implementing web api(s).

At first, I'll be focusing on http's different request methods. You might find this information everywhere over the web but I am just putting things together here, after that I'll jump right into http methods with respect to web api(s).

HTTP Methods (specification 1.1)

GET
   As the word itself says, GET should always and only be used to request a particular representation of a resource. 

HEAD
   Asks for the response identical to the one that would correspond to a GET request, but without the response body. This is useful for retrieving meta-information written in response headers, without having to transport the entire content

POST 
    Requests that the server accept the entity enclosed in the request as a new subordinate of the web resource identified by the URI. The data POSTed might be, as examples, an annotation for existing resources; a message for a bulletin board, newsgroup, mailing list, or comment thread; a block of data that is the result of submitting a web form to a data-handling process; or an item to add to a database.

PUT
    Requests that the enclosed entity be stored under the supplied URI. If the URI refers to an already existing resource, it is modified; if the URI does not point to an existing resource, then the server can create the resource with that URI.

DELETE
    Deletes the specified resource.

TRACE
    Echoes back the received request so that a client can see what (if any) changes or additions have been made by intermediate servers.  
  
OPTIONS
    Returns the HTTP methods that the server supports for the specified URL. This can be used to check the functionality of a web server by requesting '*' instead of a specific resource.

CONNECT
    Converts the request connection to a transparent TCP/IP tunnel, usually to facilitate SSL-encrypted communication (HTTPS) through an unencrypted HTTP proxy.

PATCH
    Is used to apply partial modifications to a resource

Now we understand what is the purpose of each method from HTTP. Lets now jump into web api(s) and when to use which HTTP method:

GET:
    GET supports very efficient and sophisticated caching and its primary purpose is to get resource. Caching used in GET ensures that you might not have send request to server. GET is also idempotent, which means if you send a request to server and you dont get result you simply dont know whether your resource has reached the server or not and you can simply issue another request, whereas purpose of.

POST
    POST is "create a new resource", so it should not be used to get resource representation. Normally it is seen that POST is always used to get resources which can easily done using GET, doing it this way also decrease application performance as we explicitly ignore cache used by GET to fetch resources.

PUT
     Purpose of PUT is to update a particular resource and if it does not exist create that resource. Common practice which is wrongly followed is PUT is sometimes never used, developers use POST for both update and create purpose which is wrong as per HTTP specification.

DELETE
     DELETE is used to delete a particular resource(s). But it has been observed that POST/GET are used interchangeably to achieve this purpose which violation of HTTP specification.


I hope this little article will help in clearing concept of HTTP methods and their use in web api(s).

References: