The Pros and Cons of Being RESTFul with HATEOAS: Exploring what it takes to achieve RESTFul architecture

Despite the advancement and popularity of RESTful APIs, most companies do not adopt the highest level of RESTful maturity, known as HATEOAS (Hypermedia as the Engine of Application State). To understand why this happens, it is important to know the RESTful maturity levels defined by Leonard Richardson, which describe the progression of API design in terms of utilizing web capabilities.

According to Ian Robinson, something he found appealing about this model when Leonard Richardson first introduced it was its relation to common design techniques. Below, I detail each level of maturity with examples in C#.

Level 0: The Initial Stage

The most basic level of a RESTful API is Level 0, also known as The Swamp of POX (Plain Old XML). Here, the API operates as a traditional remote service, using a single endpoint and exchanging data in a specific format, such as XML or JSON.

- Pros: Simplicity of implementation, easy to understand and use for basic operations.

- Cons: Lack of structure, difficult to scale and maintain, limited use of web standards and principles.

Level 1: Resources

In Level 1, the API begins to introduce resources, each with its own endpoint. Instead of having a single endpoint for all operations, the API maps specific resources to distinct URIs. This level addresses the complexity issue by using the divide and conquer technique, breaking a large service endpoint into multiple resources.

- Pros: Better organization, clarity in defining resources, easier navigation and maintenance of the API.

- Cons: There may still be a lack of full utilization of HTTP methods and status codes, limiting the efficiency and standardization of operations.

Level 2: HTTP Verbs

Level 2 incorporates the proper use of HTTP verbs (GET, POST, PUT, DELETE, etc.) to define actions on resources. Additionally, HTTP status codes are used to communicate the result of operations. This level introduces a standard set of verbs so that we can handle similar situations in the same way, removing unnecessary variation.

- Pros: Greater standardization and compliance with REST principles, better operation semantics, native support for caching and security.

- Cons: May require a deeper understanding of HTTP methods and status codes, increasing the initial complexity of implementation.

Level 3: HATEOAS

The highest level, Level 3, is where the API becomes fully RESTful with the introduction of HATEOAS. Here, API responses include hypermedia links that allow clients to dynamically discover how to navigate between resources and what actions are possible. This level introduces discovery, providing a way to create a self-documented protocol.

- Pros: Self-discovery, flexibility, decoupling between client and server, allowing smoother changes and fewer disruptions.

- Cons: High implementation complexity, larger response sizes, requires greater understanding and handling capacity by client developers.

Why Is HATEOAS Not Widely Adopted?

Despite the benefits of HATEOAS, many developers and companies opt not to adopt this level of RESTful maturity. Here are some reasons:

1. Complexity and Overhead: Implementing HATEOAS adds significant complexity, both in development and maintenance of the API. This can lead to development overhead and potential performance issues.

2. Perceived Need: Not all APIs require the full capabilities that HATEOAS offers. For many simple use cases, hypermedia navigation is seen as unnecessary.

3. Adaptation and Knowledge: Adopting HATEOAS requires a shift in design mindset and a deep understanding by developers. This may require additional training and a significant investment in time and resources.

4. Tools and Support: Not all development tools and frameworks offer robust support for HATEOAS, which can make its implementation and consumption more difficult.

5. Client Challenges: Clients consuming the API also need to be prepared to handle hypermedia. Many existing clients may not be set up to effectively interpret and use hypertext links.

Conclusion

Leonard Richardson's RESTful maturity levels offer a valuable guide for API design, from the most basic level to fully RESTful with HATEOAS. While HATEOAS offers significant benefits in terms of flexibility and self-discovery, its complexity and the challenges associated with its implementation and consumption lead many companies to opt for lower levels of maturity that effectively meet their needs without the additional overhead.

Choosing the ideal RESTful maturity level should balance benefits and complexity, always aligning with the specific project needs and the development team's capacity.

To learn more, check out these links:

- [Richardson Maturity Model - Leonard Richardson (2008)](https://www.crummy.com/writing/speaking/2008-QCon/act3.html)

- [REST Foundations - DZone Refcardz](https://dzone.com/refcardz/rest-foundations-restful?chapter=3)

- [Richardson Maturity Model - Martin Fowler](https://martinfowler.com/articles/richardsonMaturityModel.html)