What are the 6 characteristics of a REST API?

REST API architecture was put forward by Dr. Roy Fielding in his 2000 doctoral dissertation. This architecture has been around for roughly 23 years and most of the popular APIs follow it. Despite this widespread use, most programmers are still unaware of the six underlying characteristics that define a REST or RESTful API.

You can ensure you are not among that list of programmers by going through Dr. Fielding's 180-page dissertation. Or better yet, spend the next few minutes reading this very article where we go over this list of characteristics and discuss why each one is important. We can assure you the latter option is more fun and time friendly 😄

Basics of a REST API

Before we dive into the six characteristics, it is useful to understand how REST APIs work. Feel free to skip this section if you have already used REST APIs before.

REST architecture (and in turn the REST API) revolves around the concept of resources. A resource can be any data that is stored on the server. For Facebook, a resource might be status updates. Similarly for Twitter, a resource might be tweets. You perform actions on these resources. Moreover, each resource has a dedicated endpoint that allows you to interact with the resource (reading, deleting, updating, etc.).

There are four main types of requests in REST APIs. As REST is built on HTTP, these types are based on the pre-existing HTTP verbs as well:

1. GET: Used to retrieve information from the server. A GET request should not modify the state of the server and is typically used to retrieve a representation of a resource.
2. POST: Used to send information to the server. A POST request is typically used to create a new resource or update an existing one.
3. PUT: Used to update an existing resource. A PUT request should completely replace the current representation of a resource with the one specified in the request.
4. DELETE: Used to delete a resource. A DELETE request should remove the specified resource from the server.

Here is what a typical POST REST request might look like:

With the basics down, it is time to dive into the six characteristics.

Six Characteristics of REST

REST was introduced to cater to the needs of scalable and performant web services. This is why REST puts extreme emphasis on making sure that the APIs following this architecture follow certain principles that help them stay performant, highly available, extensible, and easily scalable. These principles together form the six characteristics of a REST API. Let's take a look at them:

1. Client-Server Architecture

RESTful APIs are built with a client-server architecture, meaning that the client sends a request to the server and the server sends back a response. The client can be any device or application that can make HTTP requests, while the server is the application that provides the API and responds to client requests. This characteristic allows for the separation of concerns, making it easier to develop, maintain, and scale both of these components independently.

2. Statelessness

RESTful APIs are stateless, meaning that each request made by the client to the server contains all the information necessary for the server to fulfill the request, without relying on any previous requests or server-side storage. This is why every authenticated REST request has to carry an authentication token in the request headers.

This does increase the request size but it lets the server scale without worrying about storing state information across two separate requests.

3. Cacheability

It is important to utilize methods to reduce the load on the server. Therefore, RESTful APIs implement some sort of caching. This means that the API responses can be cached by the client, allowing for faster response times in subsequent requests for the same resource. This reduces the load on the server and improves performance, as the server does not need to generate the same response for each request.

As each request in REST has to carry authentication tokens and the relevant state required to act on the server, the benefits of this characteristic become visible pretty quickly for any API with decent traffic. Even with a cache timeout of 5s, you can help prevent thousands or millions of requests over a few seconds.

4. Layered System

Future-proof APIs should be modular and each module should be updatable or swappable transparently. Hence, REST requires the APIs to be designed as a layered system, where the client interacts with the server through a single endpoint, while the server can interact with multiple backend systems. This provides a separation of concerns and makes it easier to add new backend systems, change existing ones, or perform maintenance, without affecting the client. An example of this might be how a server can update the mechanism for load-balancing but the client doesn't need to be made aware of that. The client can continue communication the same as before.

5. Code-On-Demand

This is an optional characteristic as it can lead to unintended side effects and exploits. This characteristic means that the server can send back code to be executed by the client instead of data. This can help extend the functionality of the client and lead to more dynamic and customizable interactions. However, this also requires that the client can understand and execute the code that the server sends back. This has therefore reduced the frequency with which this characteristic is adhered to. Moreover, if the server is hacked, the clients will automatically be hijacked as they will execute whatever the server responds with. This glaring security gotcha has also hindered the adoption of Code-On-Demand.

6. Uniform Interface

This means that the API uses a common set of methods, such as GET, POST, PUT, and DELETE, to access resources, and a standard format, such as JSON or XML, for requests and responses. This makes it easier for clients to understand and interact with the API, as all resources are accessed in a consistent manner. The uniform interface also makes it easier to implement API versioning, as new functionality can be added by defining new resources and methods, without affecting existing ones.

Conclusion

This was a quick run-down of the six characteristics that dictate which APIs can be considered RESTful. You do not need to know about them to use a RESTful API but it is useful to understand the background and thought process behind why REST APIs are implemented the way they are. This will make sure you can use them more effectively.

Before letting you go, it would be wrong not to mention our very own RESTful API that helps developers scrape websites and extract relevant data without getting blocked. Go through our extensive documentation and help yourself to our generous monthly free plan and learn more about REST and APIs ✨