REST vs RESTful APIs: You're probably missing the third level.

When discussing APIs, the terms "REST" and "RESTful" often surface. Let’s clarify the distinction and explore them.

What is REST?

REST (Representational State Transfer) is an architectural style for designing distributed systems, particularly web services. REST is based on a set of principles, including statelessness, resource identification through URIs, and uniform interfaces.

REST is no more than a guideline that informs how web services should be structured to maximize scalability and performance.

What is RESTful?

In essence, a RESTful API is one that adheres to the constraints of REST.

Leonard Richardson's Maturity Model breaks down RESTful APIs into four levels:

1. Level 0: Uses HTTP as a transport protocol (e.g., sending XML or JSON payloads).
2. Level : Introduces distinct resource URIs, mapping entities to endpoints using nouns (e.g., /users, /products).
3. Level 2: Fully utilizes HTTP semantics, including methods (GET, POST, PUT, DELETE), status codes, and headers.
4. Level 3: Implements HATEOAS (Hypermedia as the Engine of Application State), where responses contain links to related resources, enabling navigation dynamically.

At the end of the day, a RESTful API is only fully REST-compliant if it meets all four levels.

Most APIs adheres to the first 3 levels. The question now is: Is it worth to implement the last one as well (HATEOAS)? When should I adopt it?

Upside of implementing HATEOAS in your RESTful API

1. Discoverability: With HATEOAS, clients can navigate the API dynamically. Useful specially for public APIs.

Example: A GET /users/1 response includes:

{
  "id": 1,
  "name": "Daniel Domingueti",
  "_links": {
    "self": { "href": "/users/1" },
    "update": { "href": "/users/1", "method": "PUT" },
    "delete": { "href": "/users/1", "method": "DELETE" }
  }
}
        

Downside of implementing HATEOAS in your RESTful API

1. Complexity: Adds development overhead.
2. Performance: The extra links can lead to larger payloads and higher latency.
3. Over engineering for simple systems: If the API is small or for internal use, REST’s HATEOAS complexity may not be worth it.

Conclusion

REST is the foundation, but being RESTful requires thoughtful implementation of its principles.

While the benefits—like scalability, flexibility, and discoverability—are immense, the additional complexity must align with your project’s needs.