RESTful API

An overview of what is REST and what it means to build a RESTful API.

Definition of REST

REST stands for Representational State Transfer and is an architecture based on a set of components, connectors and data elements within a distributed hypermedia system. The focus is put on component roles and a specific set of interactions between data elements rather than on the implementation itself.

The purpose of REST is to induce to systems that complies to it the following properties: performance, scalability, simplicity, modifiability, visibility, portability and reliability.

A RESTful API is an API that implements a REST architecture. The BeRest framework gives you all the tools you need to build your own.

REST Properties

Let's take a closer look at the different properties induced by a REST architecture:

  • Performance - Interactions between components have a major impact on the user-perceived performance as well as on network efficiency.
  • Scalability - Supporting a large number of components and interactions.
  • Simplicity - Simple interfaces to interact with.
  • Modifiability - Supporting changing need by allowing components to be modified.
  • Visibility - Service agents having visibility over communication between components.
  • Portability - Components to allowing moving program code with data.
  • Reliability - Resistence of failure at the system level in case of failures within components, connectors or data.

REST Constraints

To benefit from the REST properties, a system has to confirm to the following constraints:

  • Client-Server - A uniform interface separates clients from servers making client code more portable, server code more scalable and the ability to develop on each independently, as long as the interface remains the same.
  • Stateless - No client context is stored on the server between requests, the client being responsible for maintaining such client context and sending all the necessary information to the server between each requests.
  • Cacheable - Responses from the server must define themselves as cacheable, or not, to make sure clients and intermediaries cache appropriately the responses from the servers. Doing so will remove some client-server interactions, improving scalability and performance.
  • Layered System - Clients should not rely on which server they are connected to. Intermediary servers could be used to improve system scalability by using load balancers or shared caches.
  • Code on Demand (Optional) - Servers can temporarily extend or customize the functionality of a client by transfering executable code such as compiled components.
  • Uniform Interface - This part is fundamental to the design of any REST service. It consists of identification of resources, manipulation of resources through these representations, self-descriptive messages and hypermedia as the engine of application state.

RESTful API Aspects

A web service that conforms to all REST constraints is called a RESTful API and shows the following aspects:

  • Base URI, to identify a collection.
  • Internet Media Type, such as JSON or XML.
  • Standard HTTP Methods, like OPTIONS, GET, POST, PUT and DELETE.
  • State Reference, by the mean of hypertext links.
  • Related Resources, referenced as well by hypertext links.