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