REST or REpresentational State Transfer is an API architecture style that uses a uniform interface.  A REST API is a type of API that is designed to be very flexible but follow the REST constraints. REST is not a protocol or standard – it’s a set of architectural constraints. You can read more about the various API styles in the API Style Choices article.

Headers and uri parameters are essential parts of a REST Http Request. The Http Headers can tell us about authorization, whether caching allowed and more. When a client system makes a request via REST it must send state or context with each request. State is often sent as part of the uri or as part of the authorization header.

What are the REST API constraints?

For an API to be RESTful there are six rules that it needs to follow. The rules are as follows:

1. Uniform interface
2. Client–server
3. Stateless
4. Cacheable
5. Layered system
6. Code on demand (mostly legacy)

Uniform Interface

The API should facilitate communication between the client and server as they exchange data. To efficiently exchange data we need a uniform interface.

The uniform interface is likely based on the HTTP protocols – making use of the various HTTP Methods, likely making use of the HTTP Status Codes and should be easily intuitive. If your system is using well known protocols and techniques it’s easily implemented. The blog article Understanding how to use REST API and HTTP Work explains this in more detail.

Data should be exchanged using standard formats too – JSON or XML are great choices although they aren’t the only choices available.

Client-server architecture

The main purchase of an API is to connect two pieces of software – software might be custom built and run, off the shelf, or a Software as a Service. The client makes requests and the server gives responses – it’s important that they stay separate and independent.

A well designed relationship shouldn’t need to be updated every time applications on each end change. Many APIs have thousands of different clients connecting them – when working at Caddle we hundreds of different phone variants using our mobile apps and thousands of web based users using apps that called our API each day.

For more details about the Client Server Architecture read the blog article Introduction to the Client Server Architecture.

Stateless

It’s important that each endpoint in the API be stateless which means each call must be handled independently and have no knowledge of what happened from other calls.

A lot of web sites aren’t stateless – they use a session that is stored on the server side and the client has a session identifier or code that they give each time they do something.

A stateless API means that the server receives everything from a client that they need to identify them and what they want in each request.

The major advantages of a stateless API are:

• that they can handle more clients because less resources are used, and
• each request is independent of previous ones, so if one fails they don’t all necessary fail in a sequence

Cacheable

APIs can have a lot of overhead when they process requests – making repeated requests for data that rarely changes or for the exact same data doesn’t normally make sense.

A cache allows us to temporarily store data locally for a agreed upon period of time. So essentially, if the client goes to make the call again and the agreed upon time hasn’t been fully spent it will use the stored version.

This saves us time, and costly requests that don’t really make a whole lot of sense. The blog article 6 Tips For Better Handling Traffic Spikes covers caching in quite a bit more detail.

Layered System

REST allows us to build a layered system architecture meaning that multiple servers may potentially respond to a request. A client shouldn’t be able to easily tell what system is responding to their request especially if it’s behind an API Gateway. See blog post Introduction to API Gateway for more details about how API Gateways work.

The blog post Introduction to the Layered Architecture (n-Tier Architecture) has more details about how to implement a layered architecture.

Code on Demand

For the most part, I don’t see this implemented very often because it can be a security issue but it’s okay to return code that code render a user interface widget. This used to be really popular in the early 2000’s.

Wrapping It Up

REST APIs have a number of constraints that they must adhere to be truly REST based. There’s no requirement to use a specific data type for return or in the request though.

For an API to be RESTful there are six rules that it needs to follow. The rules are as follows:

1. Uniform interface
2. Client–server
3. Stateless
4. Cacheable
5. Layered system
6. Code on demand (mostly legacy)