RESTful API: The Principles and Constraints
What is a REST API?
REST is an architecture that allows for more flexible and scalable system communication³. REST stands for Representational State Transfer⁴. A RESTful API uses HTTP requests to retrieve, update, create, or delete data. These requests are known as GET, PUT, POST, and DELETE⁵. In order for an interface to be considered truly RESTful, it must follow six architectural constraints, outlined below.
Constraint #1: Client-Server
In a RESTful API, there must be a client side and a server side. This separation between data storage and the user interface allows for better scalability and flexibility⁴.
Constraint #2: Uniform Interface
There are four guiding principles of the uniform interface between client and server.
- Resource-Based: A RESTful API is based on the abstract concept of a resource, which is identified by a uniform resource identifier (URI). A resource is any data that can be named, such as images or documents. It points to a set of data, so even though the data may change, the resource itself will not. For example, a resource can point to all the users in a database. The all users data may change over time, but the resource pointing to it will not. Additionally, two different resources can point to the same set of entities. Even though they map to the same information, they still remain separate resources There are two different types of resources: individual and collection. A collection points to a set of elements, while an individual resource maps to a single element¹.
- Representations of Resources: In a RESTful API, the client has no control over the modification of resources. Therefore, when the client wants to update or remove resources, it provides the server with a representation of the modified resource (typically as a JSON object). The server receives that PUT or POST request and proceeds, sending back a response status³.
- Self-Descriptive Messages: When an HTTP request is made, the browser responds with a self-descriptive message that shows what kind of request was made and that status of the response³.
- Hypermedia as the Engine of Application State (AKA: HATEOAS): After a response is made, the server lets the client know which requests it can make next. This data is known as hypermedia³.
Constraint #3: Stateless
The server must be stateless, so requests from the client should include all the information needed to fulfill them.
Constraint #4: Cacheable
In a RESTful API, responses from the server should be marked as cacheable or not cacheable. When a server response is cached, the client stores it so that the data can easily be retrieved. This saves having to make duplicate calls over the network³. It is important to cache when necessary, because caching lightens the load on the client and server, thus improving performance and scalability⁴.
Constraint #5: Layered System
In a layered system, multiple servers are used. A client has no concern if it is connected to an intermediary server or the end server, so components can easily be extended or replaced by another component¹ ⁴.
Constraint #6: Code on Demand *optional
More often than not, the information received from RESTful API requests will be static JSON or XML. However, you can also return executable code, such as Javascript⁵.
References
[1] Cámara, P. (2018). Rest Principles. Retrieved May 29, 2020, from https://ninenines.eu/docs/en/cowboy/2.7/guide/rest_principles/
[2] Levin, G. (2016, October 02). REST API Basic Guidelines — Design It Right. Retrieved May 29, 2020, from https://blog.restcase.com/restful-api-basic-guidelines/
[3] Long, L. (n.d.). What RESTful actually means. Retrieved May 29, 2020, from https://codewords.recurse.com/issues/five/what-restful-actually-means
[4] REST API Tutorial. (n.d.). Retrieved May 29, 2020, from https://restfulapi.net/
[5] Rouse, M. (2020, April 07). What is a RESTful API (REST API) and How Does it Work? Retrieved May 29, 2020, from https://searchapparchitecture.techtarget.com/definition/RESTful-API
[6] Lange, K. (2020, May 20). What are RESTful Web Services? Retrieved May 29, 2020, from https://www.kennethlange.com/what-are-restful-web-services/
