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:
