REST Design Pattern and Best Practices





There is lot of material available on net about the REST design pattern and REST way of services but still to get started you need to read a few before you could make a call. I have tried to summarize my beginning to make it easier for others.
REST: The Style of Architecture
REST (REpresentation State Transfer) is the way the whole web is organized. Web is a collection of resources which can be identified with a URI which are globally identifiable.
People do struggle to define REST. One wrong statement is "REST is a communication Protocol". REST is not protocol; it is just a style of software architecture for distributed system. REST style of Architecture shows following characteristics:
As opposed to the procedure based approach of SOAP, REST follows the action based approach to act on a resource. The actions can be described in the form of four verbs:
(In HTTP world these are referred to as Methods. There are few more methods / actions available for HTTP like TRACE, CONNECT.). The actions are synonymous to the traditional CRUD operations.
1.       Create ~ POST
2.       Read ~ GET
3.       Update ~ PUT
4.       Delete ~ DELETE
Designing RESTFul Web Services
A RESTful web service is a web service implemented using HTTP and the principles of REST. RESTFul web services are also termed as web API. Below are the best practices for designing the REST API

·         Only 2 URLs for a resource

a.     Plural form for collection
b.    Singular for an element
Resource
POST
(create)
GET
(read)
PUT
(update)
DELETE
(delete)
/employees
Create Employee
Get all employees
Bulk update
Delete all employees
/employees/abhisar

Abhisar’s
details
Update Abhisar
Delete Abhisar

Here there is one point for the notice that though ‘/employees’ represents the collection but POST is used for creation of a resource as obviously Singular URI cannot be used.The behavior is covered well in specification for each language e.g. jax-rs specification for java.
·         A URI should represent one and only one representation

If a URI represents a structure then it should represent the same structure for all actions / methods.

<employee>
<id></id>
<name></name>
<age></age>
</employee>

·         Associations should be part of URI
Ex. If an employee is part of an organization then it should be evident from URI
GET : ‘/Abc/employees/Abhisar’.

·         Variations should be handled as part of query params
Ex. If you only need the name of the employee to be returned for request of list of employees then the variation should be handled with query params
GET : ‘/employees?fields=id,name

·         URI should depict the version
APIs are modified during their life span. Existing consumers should not break with modification. This arises the need for API versioning and it should be handles through URI.
Ex. GET : ‘/v1/employees’

·         Error handling
Don’t use http error codes for application behavior; they are primarily used by the transport layer. So we should not mix it. API should always return http code as 200 if the request was received.
We should use the separate message structure which can include application error code and message.

·         Response items should be self-discoverable
If the response of GET for ‘/employees?fields=id’ is a list of employees then response can be as following
{employees : [1, 2, 3]}
Its always a better practice to return discoverable URIs in return
{employees : [‘/employee/1’, ‘/employee/2’, ‘/employee/3’]}

Well that’s all I had to say on REST as of now. Hope it helps

Comments

Popular posts from this blog

Hibernate: a different object with the same identifier value was already associated with the session

BeanDefinitionStoreException: Failed to parse configuration class: Could not find class [javax.jms.ConnectionFactory]