REST playground
The content here is under the Attribution 4.0 International (CC BY 4.0) license
The Representational State Transfer (REST) architectural style was introduced by Roy Thomas Fielding in 2000 [1] (it is availabe online as well). The architectural style is motivated by the need for long-lived, network-based applications that span multiple organizations, and it is intended to promote software longevity and independent evolution. In the time that rest was proposed the systems created were grounded in the following caracteristics:
- Challenges with tightly coupled systems: The sources imply that many existing systems were tightly coupled between client and server, often relying on fixed resource names, hierarchies, and out-of-band information.
- Remote Procedure Call (RPC): REST contrasts with RPC where out-of-band information drives interaction. The sources explain that many APIs claiming to be RESTful were in fact RPC.
- Object-specific interfaces: Systems were designed around specific objects and their corresponding interfaces, which led to less interoperability and more tightly coupled systems.
REST emphasizes a design that is focused on the long term. The following list represents the motivations behind its creation:
- Decoupling client and server: REST aims to reduce the coupling between clients and servers by having servers provide instructions to clients on how to interact with resources through hypertext. This approach allows servers to control their own namespace, rather than having clients depend on a fixed resource structure.
- In a RESTful system, the engine of application state is driven by hypertext, meaning that clients navigate through the application by selecting server-provided choices within received representations. This approach contrasts with Remote Procedure Call (RPC) where out-of-band information drives interaction.
- REST advocates for a uniform interface, where every service has the same interface, which helps to reduce coupling and improve interoperability.
- Media Types: REST emphasizes the importance of media types in defining how a representation is to be processed. Each representation contains the specific instructions for interfacing with a given service, provided in-band.
- Avoiding client knowledge of server implementation: REST aims to hide implementation details of the server from the client. Clients should not need to know if a resource is a queue or a database record. The client should interact with a resource using the instructions provided in the representation.
- Addressing resource modeling: REST is intended to address the need to identify, represent, and manipulate resources effectively. The focus is on what resources are worth representing and how to interact with them.
- Support for both machine and human-driven applications: The same design principles that apply to good human-web design are also applicable to automated agents, allowing protocols to support both types of applications by following the same architectural style.
In summary, the motivation for REST is to create a scalable, flexible, and long-lasting architecture for network-based applications by emphasizing the importance of hypermedia, media types, and a uniform interface while minimizing coupling between clients and servers. Since its inception, many developers have associated REST primarily with HTTP methods like GET, POST, PUT, and PATCH. However, Fielding’s dissertation delves much deeper into REST as an architectural style, focusing on principles and constraints rather than specific implementation details. Even today, practitioners continue to discuss and debate its applicability in modern systems.
Definitions
To get started with the REST part of things, I would like to present some definitions that I have come across during my career. Firstly, having a single source of truth about APIs is challenging due to their diverse implementations. Roy Fielding, in his dissertation, uses broad terms to depict and define the constraints of REST and how to create an API that adheres to these constraints.
Different architectural styles often suffer from a lack of implementation details, leading to various approaches and interpretations. For example, the Richardson Maturity Model (RMM), as elaborated by [2], provides a structured way to evaluate and improve RESTful APIs. The model consists of four levels, ranging from 0 to 3:
- Level 0 - Using HTTP as a way to communicate between systems: At this level, HTTP is merely used as a transport protocol without leveraging its full potential. Systems might use HTTP to send and receive data, but they do not utilize the concept of resources or HTTP methods effectively.
- Level 1 - Usage of resources to represent capabilities: At this stage, systems start to use resources to represent different capabilities. However, they might still rely on a single HTTP verb, typically POST, to perform all actions. This level introduces the concept of resources but does not fully utilize HTTP methods.
- Level 2 - Using HTTP verbs to express intent: This level involves using HTTP methods (GET, POST, PUT, DELETE, etc.) to express the intent of the operations being performed. Each method has a specific meaning and purpose, allowing for a more expressive and standardized way of interacting with resources.
- Level 3 - HATEOAS (Hypermedia As The Engine Of Application State): The highest level of maturity, HATEOAS, emphasizes the use of hypermedia links to guide the client through the interactions with the API. At this level, the API provides links to related resources and actions, allowing clients to navigate and interact with the API dynamically.
The Richardson Maturity Model provides a common ground to start analyzing REST implementations and improving their structure. It is widely used across different authors and practitioners to assess and enhance the maturity of RESTful APIs [3].
In my experience, most APIs I have worked with fall between Level 0 and Level 2. It is rare to encounter an API that fully implements Level 3 (HATEOAS) in a professional setting. For example, [4] depicts the design of a REST API up to Level 2, highlighting the practical challenges and considerations involved in achieving higher levels of maturity.
REST API Quiz
Caracteristics
Authentication
A common feature for APIs to have is authentication and authorization. Both terms are used together but refer to different caracteristics. The later provides fine granular permissions checks allowing or blocking the access to certain features of the API, whereas the former is most common, providing a way to consumers to indify themselves.
In the real of authentication, there are different approaches to handle that when dealing with REST APIs. Let’s dive in that next.
References
- [1]R. T. Fielding, “Architectural Styles and the Design of Network-based Software Architectures,” 2000 [Online]. Available at: https://www.bibsonomy.org/bibtex/217b085721104f50d2f804bd1df197edc/gromgull. [Accessed: 29-Aug-2020]
- [2]M. Fowler, “Richardson Maturity Model,” 2010 [Online]. Available at: https://martinfowler.com/articles/richardsonMaturityModel.html. [Accessed: 17-Sep-2021]
- [3]H. Subramanian and P. Raj, Hands-On RESTful API Design Patterns and Best Practices: Design, develop, and deploy highly adaptable, scalable, and secure RESTful web APIs. Packt Publishing Ltd, 2019.
- [4]J. María, “Rest API. Best Practices to design at the 2nd Maturity Level,” 2022 [Online]. Available at: . [Accessed: 02-Sep-2022]