← Back to Blog

Backend API architecture

Loading the Elevenlabs Text to Speech AudioNative Player...

The great API debate: Richardson Maturity Model vs. GraphQL

The ever-present debate in web development is how to design APIs well, and REST and GraphQL are the two names that come up most. They both aim to improve the way applications exchange data, but they approach the problem from fundamentally different perspectives. The Richardson Maturity Model provides a concrete scale for grading REST APIs, and GraphQL can be placed on the same scale, which makes the comparison a lot easier to talk about.

Understanding the Richardson Maturity Model

Leonard Richardson came up with this model as a framework for grading how closely an API follows the principles of REST (Representational State Transfer). It’s not a technology itself, just a way to measure how “RESTful” an API is. The model has four levels, from 0 to 3, and each level builds on the previous one.

  • Level 0 is the Swamp of POX (Plain Old XML). At this level, the API uses a single URI and a single HTTP method (typically POST) for all operations. This is essentially remote procedure calling (RPC) over HTTP.

  • Level 1 introduces individual resources, each with its own URI. Instead of a single endpoint, you have multiple URIs to identify different resources (e.g., /users, /products).

  • At Level 2, the API starts to use different HTTP methods for different actions on resources, such as GET for retrieving data, POST for creating, and DELETE for removing. This matches the intended use of the HTTP protocol.

  • Level 3 is the highest level of REST maturity: hypermedia controls, or HATEOAS (Hypermedia as the Engine of Application State). API responses include links and forms that guide the client on what actions it can take next. Clients can navigate the API dynamically without prior knowledge of all endpoints.

Introducing GraphQL: a query language for APIs

Facebook developed GraphQL and released it in 2015. It is a query language for your API and a server-side runtime for executing those queries. Compared with traditional REST APIs, it is often more flexible and efficient. With GraphQL, the client specifies exactly what data it needs, and the server responds with only that data, which avoids over-fetching (receiving more data than needed) and under-fetching (needing to make multiple requests to get all the required data).

GraphQL APIs are organized around a schema that defines the types of data a client can request. The schema acts as a contract between the client and the server: clients can only ask for what the schema allows, and they get clear errors when they don’t. Unlike REST, which uses multiple endpoints, a GraphQL API typically exposes a single endpoint.

The clash of philosophies: Richardson Maturity vs. GraphQL

Comparing the Richardson Maturity Model and GraphQL is not a direct, apples-to-apples comparison. The Richardson Maturity Model is a way to evaluate REST APIs, while GraphQL is a completely different architectural style. In practice, a typical GraphQL API lands around Level 2. It uses a single endpoint and the POST method for most operations, so it does not fully adopt the resource-based, multi-endpoint approach of higher-level REST APIs.

Here’s a breakdown of the main differences:

  • The number of endpoints is the biggest difference. As a RESTful API moves up the Richardson Maturity Model, it gains many endpoints, one per resource. A GraphQL API, on the other hand, has a single endpoint.

  • With a REST API, the server determines the structure of the response. With GraphQL, the client requests the specific data it needs, which can lead to more efficient data transfer.

  • A fully mature REST API (Level 3) relies on HATEOAS, which is absent in GraphQL. GraphQL’s schema provides a similar “discoverability” feature, but it’s a build-time contract rather than a runtime guide.

  • The GraphQL specification itself is protocol-agnostic: it does not dictate the use of HTTP. In practice, though, it is almost always implemented over HTTP.

Can they coexist?

The Richardson Maturity Model and GraphQL are built on different philosophies, but they are not mutually exclusive. In fact, they can complement each other. For example, a GraphQL server can act as a gateway that sits in front of multiple RESTful microservices. Clients get GraphQL’s flexible querying, while the underlying services still follow REST principles.

The verdict: which is better?

The “better” approach depends on the specific needs of your application. The Richardson Maturity Model provides a clear path to building scalable RESTful APIs that make full use of the HTTP protocol. REST is a well-established standard with solid caching support and tight integration with the web’s infrastructure.

GraphQL, on the other hand, takes a newer, more flexible approach that can be particularly beneficial for complex applications with diverse data needs, such as mobile apps. Its ability to fetch exactly the right data in a single request can lead to real performance improvements.

The choice between a RESTful architecture and GraphQL is a trade-off. Developers who understand the principles behind the Richardson Maturity Model and the capabilities of GraphQL can make an informed decision for their project.