Top 10 Design tips for building REST APIs

Software Design is functional Art. An average person today deals with at least 25 instances of such functional digital art daily in form of mobile or a web app. Most digital software thrives on a backbone of a well written API and REST is one of the preferred and versatile styles for writing such scalable APIs.

The acronym REST (Representational State Transfer) was coined by Roy Fielding an architectural style in his doctoral dissertation (https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm) to lay down the guidelines for scalable architecture that would simplify application design by enabling a web programmer to breakdown the design of large scale distributed websites into smaller independent self sufficient resources.

Here are the top design considerations that would make it easier to write efficient REST APIs.

Client-Server Architecture

A REST design must follow a client-server architecture. The client and the server should have no overlap in their concerns. The server stores and/or manipulates information and makes it available to the user in an efficient manner. The client takes that information and displays it to the user and/or uses it to perform subsequent requests for information.

This separation of concerns is important to let both the client and the server evolve independently as long as the interface stays same.

Statelessness

REST Applications are stateless. That means the communication between the client and the server always contains all the information needed to perform the request. Session state should be kept entirely on the client’s side. If access to a resource requires authentication, then the client needs to authenticate itself with every request.

Cacheability

REST is cacheable. The client, the server and any intermediary components can all cache resources in order to improve performance.

Uniform Interfaced Architecture

REST provides a uniform interface between components. This implies that all components follow the same rules to speak to one another. It also makes it easier to understand the interactions between the different components of the system.

Layered System Design

All REST applications should be designed as a layered system. Individual components cannot see beyond the immediate layer with which they are interacting. This means that a client connecting to an intermediate component, like a proxy, has no knowledge of what lies beyond.

This allows components to be independent and thus easily replaceable or extendable.

Code on Demand

REST optionally provides code on demand. Code may be downloaded to extend client functionality. This is optional however because the client may not be able to download or run this code, and so a REST component cannot rely on it being executed.

HTTP Verbs

REST sticks to the methods provided by the protocol. This means following the meaning of GET, POST, PUT, and DELETE religiously.

• POST is always for creating a resource ( does not matter if it was duplicated )
• PUT is for checking if resource is exists then update , else create new resource
• PATCH is always for update a resource and only contains the fields to be updated
• DELETE is self explanatory

Understandable Error messages

Since REST APIs are designed to be treated as Resources, once defined and deployed they will be accessed from a range of interfaces. To make the API universally applicable, the programmer needs to make sure that the error messages make sense and follow an understandable standard like using the HTTP error codes. Using custom error messages would need custom code to handle these messages everywhere the REST API would be accessed and need comprehensive documentation.

HATEOAS : Hypermedia as the Engine of Application State

A new acronym in the REST world is HATEOAS i.e. Hypermedia as the Engine of Application State . This means the server provides information about the data or actions performed in the form of hypermedia. REST architectural style allows hypermedia links(URLs) in the response contents so that the client can dynamically navigate to the appropriate resource by traversing the hypermedia link.

Addressable Resources.

Each endpoint in the REST API is encapsulating a resource which is an object with a type, data and a set of standard HTTP methods that operate on it. Resources could be related to other resources or exist independently.

The Web application designer decides how the collection of resources would be addressed at each endpoint level. An endpoint may encapsulate a collection or a resource collection depending upon the data accessibility requirements .Each resource in a REST design should have an ID or an accessible URI in REST APIs

It is the task of the designer to build the REST resource model in a way such that each endpoint returns data efficiently while maintaining independence across endpoints.

REST Endpoints named as nouns

A quick indicator to judge a REST design is to see the names of the URIS defined. The focus while designing resources should be on the relationship between resources and its sub-resources. These resource URIs are endpoints for RESTful services.

For example consider an application where device is a top-level resource. And configuration is sub-resource under device. A good set of URIs would be

/devices

/devices/{id}

Notice that these URIs do not use any verb or operation. It’s very important to not include any verb in URIs and let the http verbs decide the behaviour of the endpoint.