Thoughts on REST API's

Published May 15, 2020

The content here is under the Attribution 4.0 International (CC BY 4.0) license

The architecture pattern REST was introduced by Roy Thomas Fielding in 2000 [1], since then, developers have addressed the REST pattern as something related to the type of requests, such as GET, POST, PUT and PATCH, even though the dissertation presented goes deeper in the architectural style, rather than implementation details.

This post aims to present resources on how to implement REST as well as thoughts on what I saw enterprises doing APIs, sometimes REST and sometimes not so.

Definitions

To get started with the REST part of things I would like to start presenting some definitions that I came across during my career. To begin with, having a single source of truth about APIs is difficult, since its conception Roy uses broad terms to depict and define what are the constraints of REST and how to create an API that follows those constraints.

Different architectural styles suffer from the “lack” of implementation details, thus, leading to many approaches. For example, [2] elaborates on a maturity model for REST (Richardson Maturity Model - RMM), in total there are 4 levels, starting from 0 until 3:

  • Level 0 - Using HTTP as a way to communicate between systems.
  • Level 1 - Usage of resources to represent capabilities, at this stage, systems might use only one HTTP verb, which usually is the POST verb.
  • Level 2 - Using HTTP verbs to express intent
  • Level 3 - The last one is named HATEOAS (Hypermedia As The Engine Of Application State)

The maturity model gives a common ground to start analyzing the REST implementation and trying to improve its structure, being used across different authors [3].

Therefore, APIs I have worked with usually are between Level 0 and 2, I don’t recall seeing professionally an API that is Level 3, for example, [4] depicts the design of a REST API till level 2.

  1. [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. [2]M. Fowler, “Richardson Maturity Model,” 2010 [Online]. Available at: https://martinfowler.com/articles/richardsonMaturityModel.html. [Accessed: 17-Sep-2021]
  3. [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. [4]J. María, “Rest API. Best Practices to design at the 2nd Maturity Level,” 2022 [Online]. Available at: . [Accessed: 02-Sep-2022]
Made with 💖 by @MatheusMarabesi