Best Practices For REST API Design

Why This Blog?

This blog highlights REST Best Practices intended for the developers who are interested in creating RESTful web services that provide high reliability and consistency across multiple service suites. We all know there are various resources on best practices for creating RESTful web services.

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 a major concern on best practices and conventions.

What Is REST?

REST is an abbreviation of Representational State Transfer. REST represents the architectural style of the World Wide Web (WWW). REST is an approach to communication that 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 useful resource.

We use an HTTP verb (POST, PUT, GET, DELETE, etc.) to indicate what operation the REST API has to perform. Resources are identified by URIs. It is possible to have multiple URIs pointing to the 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.

Bad practice is to use verbs like:

/getAllCustomers

/createNewCustomer

/deleteCustomers

Nouns are good and verbs are bad when it comes to rest standards. You can use the following easily understandable structure for every resource:

2. GET method and query parameters should never be used to update or alter the state:

Never use GET to alter or state changes. Use GET, POST or DELETE to alter the state.

3. Use plural forms of the noun:

Keep the resource naming simple by following plural forms of nouns. Even though you might think that it is grammatically incorrect, but the best standard for REST practices is to use plurals.

/customers instead of /customer
/customers/12345 instead of /customer/12345

4. Use sub-resources for relations:

If you have some resource which is related to another resource then it is implied to use sub-resources:

GET /customers/1/products: Returns a list of products purchased by customer 1

5. Use HTTP headers for serialization formats:

The client-side and server-side both should know and use the format that is being used for communication. This format has to be specified in the HTTP-header.

Accept: It defines a list of acceptable response formats.
Content-Type: It defines the request format.

6. Error handling and using status codes:

It is very difficult to work under situations where proper error handling is ignored. Just returning of HTTP 500 with a stacktrace log is not enough.. We need to make proper usage of the HTTP status codes that have been covered in the earlier part.

7. Include scope for paging, sorting, filtering and field selection:

Pagination:

Use limit and offset for pagination. It is not only flexible for the user but also common in the leading databases.

• GET /customers?offset=5&limit=20

Sorting:

Ascending and descending sorting should be provided. Also allow sorting over multiple fields.

• GET /customers?sort=-age,+lastName

Filtering:

We can make use of unique query parameter for all fields or may be use a query language for filtering purpose.

• GET /customers?age>=24 Returns a list of customers whose age is equal to greater than 24.

Field Selection:

It is a very common practice that mobile clients wish to display only a few attributes. They don’t want to display or use all the attributes of a resource. Thus an API should have the ability that allow the mobile clients to choose the returned fields. This helps to save the mobile battery, reduce network traffic, and speeds up the API usage.

• GET /customers?fields=name,age,contactNumber

8. Documentation:

I hope the above content is easily understandable and lets you get started with developing REST API with some good level standards and consistency in your coding style. Just follow these REST best practices and you’re all set.

One last suggestion is to maintain an updated API document. This document should be shared and accessible to all concerned people. Most client-side developers should check the API document before starting the integration of web services. The doc should cover all necessary information like request URL, response body format, headers, etc. For every API try to cover with an example of request body and response bodies with all the alternative responses including error and success.