During my bootcamp, I learned a bit about REST APIs but not in any great details. As REST APIs are one of the most common styles, I decided to dive in deeper to learn more about what makes an API RESTful.

REST is an architectural style that was developed by Roy Fielding in his dissertation from 2000 (see link in resources below). It is not a standard but a set of recommendations and constraints that uses existing protocols (think HTTP) to create a flexible and lightweight web API.

There are six constraints that define a RESTful API, though one is optional.

  1. Client-Server: Keep the client and the server separate. Allow each to scale and evolve independently of one another. Requests and responses between the client and the server are handled by HTTP.

  2. Stateless: Requests from client to server are stateless. All the information needed for the the server to understand the request needs to be sent with the request. Store all state on the client.

  3. Cacheable: Data sent within a response can be explicitly or implicitly labeled as cacheable or non-cacheable. It is encouraged to cache data because REST is stateless.

  4. Uniform Interface: In separating the client and server, create a UI that standardizes communication between them, possibly through HTTP with URI resources, CRUD and JSON. There are four RESTful interface constraints:
    • identification of resources
    • manipulation of resources through representations
    • self-descriptive messages
    • hypermedia is available to the client

  5. Layer System: Server is composed of hierarchical layers that are not visible to the client or other layers. Their functions and responsibilities are separate. The client doesn’t need to know which server it’s communicating with: the actual, a proxy, or any other one. This creates a scalable and modular framework that can be used to move technologies in and out as they evolve or to add layers of security to your application.

  6. Code On Demand (optional): REST allows for code to be sent to the client.

Another important part of a RESTful API is the resource. The resource is any information that can be named, and can be a variety of different formats (i.e. document, image, collection of resources, etc.). REST uses resource identifiers and resource representations are sent via the API. These resource representations are the current state of the resource and contain data, metadata and hypermedia links. Resources are separate from their resource representations so that their content is accessible and manipulated without changing the original. Resource representations should be self-descriptive so that the client can interact with them based on their associated media type.

One of the easiest things to confuse is REST and HTTP. It can often seem that a RESTful API is just a simple API that utilizes HTTP methods. A true RESTful API, however, must conform to the constraints above.

REST’s architectural style is often used because it’s flexible and lightweight. It can handle many types of calls and return different types of data. Even though all state must be kept on the client side, if caching is used efficiently calls between the server and client can be reduced.

Resources:
Roy Fielding’s Dissertation
What is REST from RESTFULAPI.net
What is a REST API? from Sitepoint
What is a REST API? from MuleSoft
REST from Mozilla
REST vs. RESTful from NDepend
What is a REST API? from RedHat