An introduction to RESTful API design.
So what makes an API RESTful? I’m sure the term REST API or RESTful API has come across your screen countless times in your coding journey. This article gives an introduction to RESTful API design principles.
Before diving into the six constraints, I’ll briefly describe what an API is and how REST APIs work. API stands for Application Programming Interface. REST stands for REpresentational State Transfer. It is an API architecture with design principles for client-server communication and features.
RESTful APIs communicate through HTTP requests to perform CRUD (create, read, update, and delete) operations in a resource. These operations correspond with method requests (GET, POST, PUT, DELETE). A POST request adds information, a GET request retrieves information, a PUT request updates information, and a DELETE request deletes information. An API that follows the six constraints outlined below is considered RESTful.
The dissertation by Roy Thomas Fielding coining the term REST API can be found here.
1. Client-Server Independence
In RESTful design, the client and server must be distinct from one another. The client requests information with a Uniform Resource Identifier (URI), and the server responds to the request through HTTP/HTTPS. Both the client and server should evolve independently. This independence allows for scalability on both sides.
2. Stateless
The Stateless constraint means that the client state is not stored between requests. The request from the client provides the server with enough information to understand the request without needing to remember any client state. Not storing data about the client request improves scalability.
3. Uniform Interface
A Uniform Interface ensures standard client-server communication across platforms. With REST API architecture, a request for the same resource should have the same data. As well as response status codes from the server such as 200 ok, 401 unauthorized, etc.
4. Layered System
The client does not always communicate directly with the server. There may be layers of communication. For architecture with several layers, each layer only knows about its immediate communication layer. The layered system allows for intricate tasks to be completed without needing to understand the complexity of what is being done to receive a response.
5. Cacheable
Cacheable data is information in the response that can be stored and used later.
Server responses should declare if the data is cacheable. For network efficiency, the data in a response from the server is either implicitly or explicitly labeled cacheable or non-cacheable. For cacheable data, the client can reuse the response for future requests.
This constraint improves performance for clients while reducing the payload and improving scalability on the server.
6. Code on Demand(Optional)
The final “constraint” is optional. Code on Demand allows for logic to be sent from the server to the client for execution. The server can send some executable code to the client. For example, if an API sends a < script > tag in its response, the client will execute the JavaScript.
There you have it, the six REST API architecture constraints. Hopefully, this helped fill in some knowledge gaps or gave you a good refresher on RESTful APIs.
Oldest comments (9)
Good explanation.
Formally correct introduction. But… having developed restful api for a while, Imho the first 3 rules are the core and really important to understand what restful is. You cannot have a restful api without respecting the first 3 constraints, but you can implement a restful api ignoring 4,5,6. And never used the 6th until now.
Formally not correct. To get properly RESTful systems, you must implement ALL the non-optional constraints. If not, you are just implementing HTTP-based APIs, also known as Web APIs.
See this to learn more: dzone.com/articles/please-dont-cal...
Yes, formally. The article you have posted is emphasizing a key point in uniform interface, that is in fact one of the first 3 constraints in the article we are commenting. I know that to call an api restful you have to formally support at least five of the constraints with exception of cod, I’m just saying some of them have a really different weight. In an introductory post for people new to rest, I’d like to spent more words on the really core features of a rest api, instead of write the same number of words for uniform interface and cod.
But this is only my opinion, I’m more practical and less formal 😁
I totally understand your point.
Maybe it's age, but I've seen too many times misnaming, misunderstanding, and misusing technologies in the name of being practical... 😉
You are probably right.
This sounds weird to me. Maybe you wanted to refer to idempotence for some CRUD operations, but that is another story...
To obtain a uniform interface, you have to define your API following four constraints:
You should link to the seminal paper where this term was coined by Roy Fielding in his PhD dissertation: ics.uci.edu/~fielding/pubs/dissert....
Great point! Just edited with a link to Roy Fielding's dissertation.