What it means for an API to be RESTful | Andros Fenollosa

I am sorry, but you do not know what a RESTful API is. I know you are a seasoned developer who has integrated APIs of all kinds, and you may even have dozens in production across multiple languages. But all of that only proves you have followed the industry's good practices and read immeasurable lines of documentation, which is good. However, none of it certifies your knowledge of RESTful. Don't panic! You are not alone. Most developers I know could not define it, implement it or point out its strengths either. That is why in this article I am going to explain its virtues with examples that are easy to understand. And you may well never look at an API the same way again once you finish reading. You have been warned! API RESTful is often used as a synonym for REST API (Representational State Transfer), and the nuance matters. REST is not an HTTP interface: it is an architectural style, defined by Roy Fielding in his doctoral dissertation (2000), that imposes constraints:

Client-server architecture: The client and the server must be separated. Stateless: Each client request to the server must contain all the information needed to understand and process the request. In other words, the server will not keep information about the client's state between requests. Cacheable: Responses must be explicitly marked as cacheable or non-cacheable. Layered system: The architecture can be composed of layers, where each layer has a specific function and they are isolated from each other. Uniform interface: Communication between the client and the server must be predictable, with a well-defined pattern. Code on demand (optional): The server can send executable code to the client, such as JavaScript scripts, to extend the client's functionality.

In other words, REST is a set of architectural principles for serving resources, usually over HTTP. It is so ingrained in web development, and so standardized, that it feels strange when we do not see it. And here comes the uncomfortable part: strictly speaking, REST already includes everything you are about to read in this article. Hypermedia is part of the uniform interface constraint, and "RESTful" is simply the adjective, "conforming to REST". What has happened is that popular usage has been degrading "REST" until it means "HTTP API that returns JSON", so much so that Fielding himself published a famous article in 2008, REST APIs must be hypertext-driven, complaining that we call REST any RPC dressed up in HTTP. The Richardson Maturity Model put numbers on that distance: level 0, a single RPC-style endpoint; level 1, resources with their own URI; level 2, HTTP verbs and status codes used properly; level 3, hypermedia. The vast majority of the "REST" APIs you consume every day stay at level 2. In this article I will use RESTful to refer to that level 3, the one Fielding demands. The goal is to turn an API into a predictable, standardized and self-descriptive interface. With just the base URL, the client will be able to explore every resource, without resorting to external documentation. In addition, we will have the flexibility to change routes without affecting the client, or even play with several communication protocols. But first there is a concept you must know: HATEOAS (Hypermedia as the Engine of Application State). This concept is fundamental to understanding how a RESTful API can be self-descriptive and navigable. HATEOAS (Hypermedia as the Engine of Application State) Hypermedia is one of the key characteristics of RESTful: it allows clients to dynamically discover resources through links provided in the responses. They usually live under the _links parent. { "id": 123, "name": "John Doe", "_links": { "self": { "href": "/users/123", "method": "GET" }, "update": { "href": "/users/123", "method": "PUT" }, "delete": { "href": "/users/123", "method": "DELETE" }, "friends": { "href": "/users/123/friends", "method": "GET" }, "posts": { "href": "/users/123/posts", "method": "GET" }, "search": { "href": "/search/?query={query}", "method": "GET", "templated": true } } } Thanks to this, clients can navigate the API by parsing and following the links to reach the information they need, similar to how you would browse the internet. Furthermore, since you jump between relative routes (href) using their names as identifiers (the object key), the backend could change the addresses without affecting the client. It is very powerful because the client is not tied to a fixed route structure; it moves between nodes. Notice the use of templated: true in the last link. It indicates that the href contains a URI template (following RFC 6570) that must be filled in with specific values before use. It is an elegant way to discover parameterized endpoints. For example, the client could replace {query} with "restful api" to search for related content. An honest note before we continue: the _links convention comes from HAL (Hypertext Application Language), but HAL does not define the method field; its links only contemplate properties such as href, templated, type or title.

Not every resource needs hypermedia, only the relevant ones with the right context. For example, it would make no sense to include links to a shopping cart in a blog article, but it would be interesting for an article to include the link to the author, the comments or related articles. Now that we understand the importance of HATEOAS, let's look at the rules a RESTful API must follow. The 6 rules of a RESTful API I am not making these rules up: they are the six conditions Fielding lists in the article I mentioned earlier, adapted here with examples. 1. Don't depend on a single protocol Use resource identifiers (URIs) to define resources. In other words, instead of using a URL (http://example.com/api/users/123), use a URI that indicates its location and ignores the protocol (/users/123). This way you could use others such as WebSocket, MQTT, NNTP, RPC, etc. Of course you can use HTTP, but you must not depend only on it. For example, if your API is designed to work exclusively over HTTP, it would not be strictly RESTful. 2. Don't change the protocol Don't reinvent the wheel. Don't get creative with protocols. For example, if you use HTTP, follow the conventions: GET to fetch resources, POST to create, PUT to replace, PATCH for partial updates and DELETE to remove. Use the proper HTTP response statuses: 200 OK, 201 Created, 204 No Content, 400 Bad Request, 404 Not Found, etc. Using MQTT? Use the proper commands and statuses. 3. Focus on media types, not URIs Instead of documenting each URI externally, you must make your API describe the media types it handles. It is the most misunderstood rule of the six, and for Fielding it is where almost all the descriptive effort should go.