# API Maturity in the Age of AI

The rise of AI agents, tool ecosystems, and Model Context Protocol (MCP) integrations is changing how software interacts with APIs.

For years, APIs were designed primarily for human developers.  
Developers read documentation, understood workflows, and wrote integration code.

Increasingly, however, APIs are being consumed by machines.

Agents invoke tools.  
LLMs orchestrate workflows.  
MCP servers expose capabilities dynamically.

In this world, APIs are no longer just interfaces for developers.  
**They are interfaces that machines must be able to understand and navigate.**

Which raises an important question:

> How easy is it for a machine to understand and navigate your API?

And this raises an interesting question:

> *How easy is it for a machine to understand and navigate your API?*

Interfaces that are **structured, predictable, and semantically meaningful** are easier for both humans and machines to understand.

Almost two decades ago, **Leonard Richardson** proposed a framework that captures this idea remarkably well.

It is called the **Richardson Maturity Model (RMM)**.

* * *

## What this article is about...

This article explores:

*   Why API structure matters even more in the age of **AI agents and MCP**
    
*   What the **Richardson Maturity Model (RMM)** is
    
*   How APIs evolve across the **four maturity levels**
    
*   Why most real-world APIs stop at **Level 2**
    
*   How API maturity affects **machine-driven integrations**
    

* * *

# What is the Richardson Maturity Model?

The **Richardson Maturity Model** describes how effectively an API uses the features of the web.

At its core, the model asks a simple question:

> *Are we using HTTP as a true application protocol, or merely as a transport mechanism?*

The more an API leverages the semantics of the web — **resources, HTTP verbs, status codes, and hypermedia** — the more mature it is considered.

The model defines a progression of maturity levels.

* * *

# RMM Levels at a Glance

| Level | Core Idea | API Style |
| --- | --- | --- |
| **Level 0** | HTTP as transport | Single endpoint, payload determines operation |
| **Level 1** | Resources | Multiple URIs but operations encoded in the path |
| **Level 2** | HTTP semantics | Proper use of verbs and status codes |
| **Level 3** | Hypermedia | APIs describe possible next actions |

* * *

> **Engineering Insight**
> 
> Interfaces that are structured, predictable, and semantically meaningful are easier for both humans and machines to understand.

* * *

# Example: Coffee Ordering API

To demonstrate the model, imagine we are building an API for a **coffee ordering application**.

The system supports three operations:

1.  Fetch the menu
    
2.  Place an order
    
3.  Check the order status
    

* * *

## Level 0 — One Service to Rule Them All

Level 0 represents the **lowest level of maturity**.

HTTP is used purely as a **transport layer**, and the payload determines the operation.

### Endpoint

```plaintext
POST /coffee
```

### Example Request — Fetch Menu

```plaintext
{
  "operation": "getMenu"
}
```

### Example Request — Order Coffee

```plaintext
{
  "operation": "orderCoffee",
  "coffeeType": "Latte",
  "size": "Large"
}
```

### Example Request — Order Status

```plaintext
{
  "operation": "getOrderStatus",
  "orderId": 123
}
```

* * *

## Level 1 — Resources

Level 1 introduces **multiple URIs representing resources**, but still does not fully leverage HTTP semantics.

Example endpoints:

```plaintext
GET /getMenu
POST /orderCoffee
GET /getOrderStatus?orderId=123
```

### Example Response

```plaintext
{
  "orderId": 123,
  "status": "PREPARING"
}
```

* * *

## Level 2 — HTTP Verbs

Level 2 introduces proper use of **HTTP verbs and status codes**.

This is the level most modern APIs operate at.

### Fetch Menu

```plaintext
GET /menu
```

### Response

```plaintext
{
  "items": [
    {
      "id": 1,
      "name": "Latte",
      "sizes": ["Small","Medium","Large"]
    }
  ]
}
```

* * *

### Create Order

```plaintext
POST /orders
```

### Request

```plaintext
{
  "itemId": 1,
  "size": "Large"
}
```

### Response

```plaintext
{
  "orderId": 123,
  "status": "PREPARING"
}
```

* * *

## Level 3 — Hypermedia (HATEOAS)

Level 3 introduces **Hypermedia as the Engine of Application State**.

Responses include links describing possible next actions.

### Example Response

```plaintext
{
  "orderId": 123,
  "status": "PREPARING",
  "links": {
    "self": "/orders/123",
    "cancel": "/orders/123/cancel",
    "status": "/orders/123"
  }
}
```

![](https://cdn.hashnode.com/uploads/covers/694e3ae41267e9e911e72c10/f4e93c4e-ea01-4808-9a6b-0aa6de3233e5.png align="center")

# Why Most APIs Stop at Level 2

Although Level 3 represents the highest level of maturity, **most production APIs stop at Level 2**.

Several practical reasons explain this:

**Client complexity**

Hypermedia-driven APIs require clients to dynamically interpret links.

**Tooling limitations**

Most tooling (OpenAPI, SDK generators, API gateways) assumes **explicit endpoints**, not hypermedia navigation.

**Frontend expectations**

Frontend systems prefer predictable contracts rather than dynamic discovery.

Because of these factors, **Level 2 has effectively become the practical standard**.

* * *

> **AI & MCP Perspective**
> 
> AI agents interact with APIs very differently from human developers.
> 
> Instead of reading documentation, they rely on clear structure,
> 
> predictable semantics, and discoverable workflows.
> 
> APIs that follow good REST principles naturally provide these signals.

* * *

## RMM in the Age of AI and MCP

The rise of AI agents, tool ecosystems, and Model Context Protocol (MCP) integrations makes the ideas behind the Richardson Maturity Model relevant again.

AI systems interact with APIs very differently from human developers.

They don’t read documentation or follow predefined workflows.  
They rely on signals exposed by the API itself.

These signals include:

*   Clear resources
    
*   Predictable operations
    
*   Consistent response structures
    
*   Discoverable workflows
    

APIs that follow strong design principles naturally provide these signals.

* * *

**At Level 0**, APIs expose very little structure.  
Interactions are opaque and require interpretation, making them difficult for machines to use reliably.

**By Level 2**, APIs become significantly easier for automated systems to interact with.  
Resources, operations, and outcomes are explicit and predictable.

**Level 3** — with hypermedia-driven navigation — goes a step further.  
It begins to resemble **machine-discoverable workflows**, where the API itself guides what can be done next.

This aligns closely with how AI agents explore tools and how MCP-style systems expose capabilities dynamically.

* * *

What enables this is not just better use of HTTP, but clearer expression of the underlying system.

For example:

```plaintext
GET /menu/{menuItem}/options
```

This does more than return data.

It expresses that a menu item has configurable options.

When extended further:

```plaintext
GET /menu/{menuItem}/sizes  
GET /menu/{menuItem}/milk-options  
```

Different aspects of the system become independently addressable.

This makes the API easier to explore, reason about, and compose into workflows — especially for machines.

* * *

API maturity, therefore, is not just about correctness.

It is about how easily another system can understand and navigate what is exposed.

In a world where APIs are increasingly consumed by AI agents, clarity of structure and intent becomes a fundamental requirement.

* * *

# Summary

The Richardson Maturity Model provides a useful lens for understanding API design.

*   **Level 0 — One Service to Rule Them All**  
    A single endpoint controls everything, with behavior hidden in the payload.
    
*   **Level 1 — One Method to Rule Them All**  
    Resources appear, but intent is still implicit and constrained.
    
*   **Level 2 — Federalism**  
    Structure emerges. Responsibilities are distributed, and interactions become more predictable — *no longer one power controlling everything.*
    
*   **Level 3 — Cooperative Federalism**  
    The system becomes navigable. It begins to guide clients through possible next actions — *almost as if the path is being shown, not guessed.*
    

* * *

In practice, most APIs stop at Level 2 — and for good reason.

But the real value of the model is not in reaching Level 3.

It is in asking a more important question:

> How clearly does your API express the system it represents?

At lower levels, interacting with an API feels like dealing with a powerful but opaque system — everything is possible, but nothing is obvious.

As maturity increases, structure emerges.  
Intent becomes clearer.  
Navigation becomes easier.

And at the highest level, the system begins to guide you — not unlike a well-charted world where the next step is always visible.

In a world where APIs are increasingly consumed by AI agents, not just developers, this clarity is no longer optional.

Because for machines, the API is not just an interface.

It is the only way the system reveals itself.