REST API Cheat Sheet: Structure Constraints to Define or Design It Right

31 July 2017 |

rest-api-cheat-sheet

Representational State Transfer (REST) is a technical description of how the World Wide Web works. If to imagine that the Web is a device, and it could have an operating system, its architectural style would be REST. A REST Application Programming Interface (REST API) is a type of web server that enables a user-operated or automated clients, to access resources that model a system’s data and functions. A well-designed REST API entice developers to use the web service and is today a must-have feature. But how to clearly define that the API is actually REST? Such kind of architecture describes six constraints, and we are going to describe them below in this article.

Uniform Interface

The uniform interface that any REST services must provide is fundamental to its design.

Its constraint defines the interface between clients and servers. The four guiding principles of the uniform interface are:

  • Resource-Based. Individual resources are defined in requests using URIs as resource identifiers and are separate from the responses that are returned to the client.
  • Manipulation of Resources Through Representations. When a client gets a representation of a resource, including any metadata attached, it has enough information to customize or delete the resource on the server, if  it has permission to do so.
  • Self-descriptive Messages. Each message includes a precise information that describes how to process it. The responses also clearly indicate their cache-ability.
  • Hypermedia as the Engine of Application State (HATEOAS). Clients deliver the state via body contents, query-string parameters, request headers and the requested URI. Services deliver state to clients via body content, response codes, and response headers.

Client-Server

The uniform interface divides clients from servers. This means that, for instance, clients are not concerned with data storage, which remains internal to each server, so that the portability of client code is improved. Servers are not engaged with the user interface or user state so they can be simpler and more scalable. Servers and clients may also be replaced and developed independently, as long as the interface is not modified.

Stateless

The necessary state to operate the request is contained within it as a part of the URI, query-string parameters, body, or headers. The URI identifies the resource, and the body contains the state of it. Therefore, after the server does its processing, the appropriate state, or the pieces of it communicates back to the client via headers, status and response body.

Cacheable

As the clients can cache responses, they need to be implicitly or explicitly defined as cacheable or not to prevent clients from reusing state or inappropriate data in response to further requests. Well-managed caching partially or completely eliminates some client–server interactions and improves the performance.

Layered system

A client cannot ordinarily tell whether it is connected directly to the end server, or to an intermediary along the way. Mediate servers may improve system scalability by enabling load-balancing and by providing shared caches. Layers also enforce security policies.

Code on Demand

Servers are able to temporarily extend or customize the functionality of a client by transferring logic to it that it can execute. Examples of this may include compiled components such as Java applets and client-side scripts such as JavaScript. This is the only constraint out of six that is optional.

Summary

The conclusion is that violating any constraint other than Code on Demand means that service is not strictly RESTful. Complying with all constraints, and thus conforming to the REST architectural style, will enable any kind of distributed hypermedia system to have desirable emergent properties, such as performance, scalability, simplicity, modifiability, visibility, portability and reliability.