Rest in Practice

How does your API looks like ? Is it like this below ? 

getCustomerDetailsByID (…)

  Then this article is for you.

Building RESTful web services is no more rocket science. As a basic principle, every work should start with some best practices. In this article I will share some key concepts and references that will help to design Restful APIs.

API

API (Application Programming Interface),as the name suggest it’s the interface between your consumer application and the Core system .So it should be well defined and follow the best practices to ease development and increase client adoption.

REST vs Restful

The short answer is that REST stands for Representational State Transfer. It’s an architectural pattern for creating web services proposed by Roy Fielding in a dissertation he wrote in 2000. A RESTful service is one that implements that pattern.

Resources 

REST API’s are implemented for a “resource” like Users, Accounts etc. These API’s provide way to identify a resource by its URI, which can be used to transfer a representation of a resource’s current state over HTTP.

Richardson Maturity Model

When you model your URIs after resources and use HTTP verbs you make your API predictable. Once developers know how you defined your resources, they can almost predict what the API looks like. Here again, the emphasis is on understanding the data, not the operations.

But even if you can’t make the API entirely predictable, you can document any REST service with hypertext. So, each item returned in the inventory app would contain links for deleting, modifying, or setting the inventory level of the resource. Fielding says that before a service is RESTful, it must provide hypertext media as part of the API.

Many sites don’t meet this requirement but are still called REST. Fact is, many sites break the rules in one way or another. So many that Leonard Richardson created a model breaks down REST into levels of compliance.

Below are the Maturity levels:

0 – Exporting an API over HTTP with methods called with arguments

1 – Exporting resources instead of methods (The Example given at begining of article i.e. getCustomerDetailsById follows Level 1.)

2 – Proper use of HTTP verbs

3 – Exporting hypertext with objects that make all or part of the API discoverable.

Richardson’s model is his own, and it doesn’t map directly into Fielding’s spec. Since Fielding requires level three, he would say that most apps aren’t REST anyway.

The point is many services that we generally refer to as REST, technically aren’t.

Restful API Should 

– Follow consistent design guidelines to make using them, easy and intuitive.

– Be well documented, so that semantic behaviors are understood.

– Follow accepted standards such as HTTP.

Design Flow

The Design Guides suggest taking the following steps when designing resource-oriented APIs.

– Determine what types of resources an API provides

– Determine the relationships between resources

– Decide the resource name schemes based on types and relationships.

– Decide the resources schemas.

– Attach minimum set of methods to resources.

Designing and Developing Restful APIs

Below conventions are recommended. 

1. Use Nouns in URI

REST API’s should be designed for Resources, which can be entities or services, etc., therefore they must always be nouns. For example, instead of /createUser use /users

2. Plurals or Singulars

Generally, we prefer to use plurals but there is no hard rule that one can’t use singular for resource name. The ideology behind using plurals is:

We are operating on one resource from collection of resources so to depict collection we use plural

For example, in the case of…

GET /users/123

the client is asking to retrieve a resource from users collection with id 123.

While creating a resource we want to add one resource to current collection of resources, so the API looks like the below…

POST /users

3. Let the HTTP Verb Define Action

As per point #1 above, API’s should only provide nouns for resources and let the HTTP verbs (GET, POST, PUT, DELETE) define the action to be performed on a resource.

The table below summarizes use of HTTP verbs along with APIs:

4. Don’t Misuse Safe Methods (Idempotency)

Safe methods are HTTP methods which return the same resource representation irrespective of how many times are called by client. GET, HEAD, OPTIONS and TRACE methods are defined as safe, meaning they are only intended for retrieving data and should not change a state of a resource on a server. Don’t use GET to delete content, for example…

GET /users/123/delete

It’s not like this can’t be implemented, but HTTP specification is violated in this case.

Use HTTP methods according to the action which needs to be performed.

5. Depict Resource Hierarchy Through URI

If a resource contains sub-resources, make sure to depict this in the API to make it more explicit. For example, if a user has posts and we want to retrieve a specific post by user, API can be defined as GET /users/123/posts/1 which will retrieve Post with id 1 by user with id 123.

And there are many more things to learn before you start your API journey. Below are few reference links.