Why this blog?
This blog highlights REST Best Practices intended for the developers who are interested in creating RESTful web services which provides high reliability and consistency across multiple service suites. We all know there are various resources on best practices for creating RESTful webservices. However it should also be known that many of the available resources are conflicting. Also, it’s likely not doable to refer, read and comprehend several books on this subject with a motto of implementing services “tomorrow”. This blog will enable you to quickly understand and grasp RESTful concepts with major concern on best practices and conventions.
What is REST?
REST is abbreviation of Representational State Transfer. REST represents the architectural style of World Wide Web (WWW). REST is and approach to communication which makes simple HTTP calls for inter-machine communication. REST is often preferred over SOAP because REST does not use as much bandwidth as heavyweight SOAP does which makes it a better option for use over the Internet. In REST, the calls will be message based and dependent on HTTP standards to describe these messages. REST can be understood as a simple request/response mechanism, where each request returns a response. The following fig. will give you a better idea:
RESTful API’s, more popularly termed as REST API’s are the web services written using REST architecture.
REST is resource based. When we talk about REST, it indicates things or resources as opposed to actions in SOAP. In RESTful services noun represents the resources, for example a person resource, a user resource. We use a HTTP verb (POST, PUT, GET, DELETE, etc.) to indicate what operation the REST API has to perform. Resources are identified by the URIs. It is possible to have multiple URIs pointing to same resource. RESTful API’s generally accept/return data in json or xml format.
Let’s quickly form an example with this basic knowledge before moving further. Suppose Sagar is a resource, there is a service to fetch contact information using the HTTP verb GET which will return the data like name, address, phone number, email address in JSON or XML form
REST architectural style defines following six constraints:
1. Uniform Interface
2. Stateless
3. Cacheable
4. Client-Server
5. Layered System
6. Code on Demand
Let’s have a small review of each:
1. Uniform Interface:
It defines the interface between clients and servers. Uniform Interface simplifies and decouples the architecture. It enables each part to develop or evolve independently. Uniform interface describes the following four guidelines or principles:
Resource based
Self-descriptive messages
Resource modification using Representations
Hypermedia as the Engine of Application State (HATEOAS)
2. Stateless:
It is not required for the webserver to remember the client’s state. The necessary state required to handle the request is included in the request itself, whether as part of URI, query-string parameters, body or headers.
3. Cacheable:
Clients can cache responses. Therefore Responses must explicitly or implicitly define themselves as cacheable or not which prevent the clients from reusing stale, old or inappropriate data in response to further requests.
4. Client-Server:
The uniform interface is responsible to separate the clients from the servers. Servers and clients can be developed independently. It conveys that the clients are not concerned with data storage which is internal to each server, which increases the portability of the client code. Servers are not concerned with the UI or user state, which makes the servers more scalable and simpler.
5. Layered System:
A client is unable to tell if it is connected directly to the end server or to an intermediary server. Intermediary servers may improve system scalability by providing shared caches and enabling load-balancing. Security policies can also be enforced through layers.
6. Code on Demand:
It is possible for the servers to extend or customize the functionality of a client on temporary basis by transferring logic to it that it can execute, for example: Java applets and client-side scripts like JavaScript.
HTTP Verbs/ Request Methods:
Clients specify their desired interaction method in the Request-Line part of an HTTTP request message. Each HTTP method is bound to some specific, well-defined rules and meaning within the context of a REST API’s resource model.
The primary or most commonly used HTTP verbs or more properly called as methods are GET, PUT, POST and DELETE. These correspond to create, read, update, and delete operations respectively. OPTIONS and HEAD are the other verbs but are less frequently used.
GET:
The GET method is used to read or retrieve a representation of a resource. As GET method (along with HEAD) is used for READ only purposes hence they are considered safe as they do not change the data. GET (and HEAD) are considered as idempotent, i.e., making multiple identical requests end up having the same result as a single request.
Examples:
GET http://www.myexample.com/users/orders
GET http://www.myexample.com/users/12345
GET http://www.myexample.com/users
PUT:
We use PUT method mostly for update functionalities. Use this method for PUT-ing or updating data to a known resource URI along with the request body which contains the newly-updated representation of the original resource that we intend to change.
PUT method can also be used to create a resource in cases where resource ID is provided by the client instead of the server. But we must generally use POST to create new resources where the client defined ID is included in the body representation.
PUT is not a safe method, although it is idempotent.
Examples:
PUT http://www.myexample.com/users/123
PUT http://www.myexample.com/users/orders/123
POST:
POST method is utilized to create new resources. This method is not safe nor idempotent.
Examples:
POST http://www.myexample/com/users
POST http://www.myexample.com/users/orders/123
DELETE:
As the verb suggests, it is used to delete a resource identified by the URI.
Examples:
DELETE http://www.myexample.com/users/123
DELETE http://www.myexample.com/users/123/orders
Response Status Codes:
Forty standard codes have been defined by HTTP to convey the results of a client’s request. These codes can be divided into following five categories:
CATEGORY | DESCRIPTION |
---|
1xx Informational | Indicates transfer protocol-level information. |
2xx Success | Indicates that the client’s request was accepted/processed successfully. |
3xx Redirection | Informs that the client needs to take some additional action to complete their request. |
4xx Client Error | This category of error status codes defines the client’s error. |
5xx Server Error | These error status codes indicate the server side errors. |
All Items | Description |
Let’s have a short and precise look over the success and error status codes.
HTTP response success codes: