Most RESTful APIs Aren't RESTful

When discussing REST, it's worth delving into Roy Thomas Fielding's dissertation on the subject. In his 2000 paper "Architectural Styles and the Design of Network-based Software Architectures," Fielding introduces the Representational State Transfer (REST) architectural style as a framework for designing scalable, performant, and maintainable networked systems, particularly web services.

Fielding defines REST as an architectural style optimized for the modern web, focusing on scalability, simplicity, and adaptability. He demonstrates how REST principles shape the success of the web, advocating for its adoption in designing distributed systems with universal, stateless interfaces and clear resource-based interactions.

Fielding explicitly criticizes the oversimplification of REST in CRUD-style APIs, emphasizing that many so-called "RESTful" APIs fail to implement key REST constraints, particularly the use of hypermedia for driving application state transitions. In his 2008 blog post, "REST APIs must be hypertext-driven," he states: "If the engine of application state (and hence the API) is not being driven by hypertext, then it cannot be RESTful and cannot be a REST API. Period."

Hypermedia controls are elements embedded in a resource representation that guide clients on what actions they can take next. However, many APIs fail to implement these controls, leading to a lack of adherence to the REST architectural style.

"But those [concepts] are actually design decisions made for the API at hand, chosen by their creators and have nothing to do with REST," Fielding notes. This highlights the importance of understanding the underlying principles of REST rather than relying on common misconceptions.

HATEOAS (Hypermedia as the Engine of Application State) is a fundamental principle of REST, requiring that the client dynamically discover actions and interactions through hypermedia links embedded in server responses. This addresses the core problem of client-server coupling, allowing for decoupling of the client from the server's namespace.

For example, instead of hardcoding a URI like `/users/123/posts`, the API should return a user representation with links to discover related resources. This approach enables clients to dynamically parse and navigate the API, rather than relying on hardcoded paths or external documentation.

Despite its benefits, many APIs fail to adhere to the principles of REST, instead opting for a simpler, RPC-like style that relies on HTTP-specific mechanisms. This can be attributed to practical trade-offs in tooling and developer experience, as well as the perceived cognitive overhead of implementing HATEOAS.

"Be conservative in what you do, be liberal in what you accept from others," Fielding advises. This approach encourages pragmatism and flexibility when designing APIs, prioritizing ease of use and learning over strict adherence to the REST architectural style.

In conclusion, while REST is a powerful framework for designing scalable and maintainable networked systems, many APIs fail to adhere to its principles. By understanding HATEOAS and embracing hypermedia-driven design, developers can create more flexible, evolvable, and intuitive APIs that align with the web's own principles of representation, discovery, and transition.