Sunday, April 10, 2016

What is purpose of different HTTP Request Types in RESTful Web Service?

RESTful web services heavily rely on HTTP by design. They use different HTTP methods to perform their job and uses HTTP response code to inform clients about success or failure of a particular request. REST stands for Representational State transfer and it uses HTTP to allow two systems to communicate via remote calls. RESTFul web services is a collection of REST URI which points to resources. These URI can point to a single resource of a collection of resource. For example, you would expect /employee/101 to contain details employee with 101 and /employees to return a list of all employees. In RESTFul web service, HTTP request types signify the action to take for the resource.

For example, by using HTTP GET request on /employee/101, you can retrieve details of that user.

By using POST on employe/102 would create a new user with employee id 102, PUT request type on /employee/101 can be used to update details of employee with id 101 and DELETE method on /employee/101 can be used to remove data for that id.

By the way, in the case of PUT and POST method representation would be in the request body. See RESTful Web Services by Leonard Richardson, Sam Ruby, and David Heinemeier Hansson for more details. One of the best book to learn fundamentals of RESTful WebService.

Purpose of HTTP Request in RESTful WebService

The purpose of each of the HTTP request types, when used with a RESTful web service, is as follows:

Retrieves data from the server (should only retrieve data and should have no other effect). This is also called an idempotent method. here is an example of a GET request to retrieve the book with id 123 from Server.
GET /books/123

This HTTP request type is usually used for creating an entity i.e. a resource without an id. Once the request is successfully created, an id of the newly created entity is returned as part of the response to this HTTP request. It is often used when uploading a file or submitting a completed web form.

For example, following URL will create  a new book in the server
POST /books/

Similar to POST, but used to update an existing entity. You pass the id of existing resource along with PUT request type. For example, following URL will replace the book with id 123 in the server
PUT /books/123

See RESTful Web Services by Leonard Richardson, Sam Ruby, and David Heinemeier Hansson for more details on when to use PUT and POST while creating RESTful API.

Removes the resource from the server. Similar to PUT you need to pass the id of the resource to be deleted. For example, following URL will remove the book with id 123 in the server

DELETE /books/123

Provides a means to test what a machine along the network path receives when a request is made. As such, it simply returns what was sent.

Same as the GET method for a resource, but returns only the response headers (i.e., with no entity-body). Similar to the GET request, HEAD Is also idempotent i.e. no side effect on Server.
See  REST in Practice: Hypermedia and Systems Architecture by Jim Webber, Savas Parastatidis, and Ian Robinson for more details on how to use different HTTP methods while designing RESTful API.

Allows a client to request information about the request methods supported by a service. The relevant response header is Allow and it simply lists the supported methods. (It can also be used to request information about the request methods supported for the server where the service resides by using a * wildcard in the URI.)

Primarily used to establish a network connection to a resource (usually via some proxy that can be requested to forward an HTTP request as TCP and maintain the connection). Once established, the response sends a 200 status code and a “Connection Established” message.

Here is a nice diagram showing usage of different HTTP methods in RESTFul Web Service:
meaning of different HTTP methods in REST

That's al about the purpose of different HTTP request types in RESTFul Web service, be it in Java or any other technology. Most important is to understand the difference between PUT and POST  request types, though both PUT and POST can be used to create and update an entity, POST is usually preferred for creating and PUT is preferred for updating an existing entity.

Further Learning
REST Java Web Services
REST API Automation testing from scratch-(REST Assured java)
RESTFul Services in Java using Jersey By Bryan Hansen


Vinod Kumar Kashyap said...


Fan of your blog.
A little mistake in paragraph 3.
POST for saving and PUT for updating. But you have mentioned opposite.


Javin Paul said...

Hello Vinod, thanks for pointing it out. Yes, POST is for creating and PUT is for updating, corrected it now.

asm0dey said...


NagaRaj Raj said...

good post

daltwisney said...

Where is PATCH?

Javin Paul said...

@daltwisney, Sorry, I forgot to add PATCH, thanks for pointing it out, will add it as well. Btw, PATCH can be used to update partial resources. For instance, when you only need to update one field of the resource, using PUT to update a complete resource representation might be cumbersome and utilizes more bandwidth, using PATH is better. Also, its worth remember that PATCH is neither idempotent nor safe.

Post a Comment