Modelo de Maturidade Richardson

Modelo de Maturidade de Richardson: Entenda os 4 Níveis de REST

O Modelo de Maturidade de Richardson, criado por Leonard Richardson, é uma forma de avaliar o quão RESTful uma API é. Ele mede o grau de aderência aos princípios do REST, dividindo a maturidade em quatro níveis (0 a 3) — do menos ao mais alinhado ao estilo arquitetural REST.

Nível 0 – The Swamp of POX (Pântano de POX)

Descrição: APIs neste nível usam o HTTP apenas como transporte, sem aplicar os princípios do REST. É comum ter um único endpoint e um único método HTTP (geralmente POST) para todas as operações, lembrando chamadas RPC. O termo POX significa Plain Old XML, mas também pode envolver JSON ou outros formatos.
Características:
- Um único URI (ex.: /api) para qualquer requisição.
- Uso exclusivo de POST.
- Não aproveita recursos do HTTP (métodos, códigos de status etc.).
- Respostas trazem resultados de ações, não representações de recursos.
Exemplo:

  POST /api
  <action>getUser</action>
  <id>123</id>

Problema: Baixa interoperabilidade, difícil manutenção e pouca escalabilidade.

Nível 1 – Recursos

Descrição: O primeiro passo rumo ao REST. Aqui, a API identifica recursos individuais por URIs distintas, mas ainda não usa corretamente os métodos HTTP.
Características:
- Recursos possuem URIs próprias (ex.: /users/123).
- Geralmente ainda usa apenas POST para qualquer ação.
- Não diferencia operações por métodos HTTP.
Exemplo:

POST /users/123 tanto para obter quanto para atualizar o usuário 123.
Benefício: Organiza melhor os dados e facilita a identificação de recursos.
Limitação: Ainda ignora a semântica do HTTP.

Nível 2 – Verbos HTTP

Descrição: Aqui, a API usa métodos HTTP corretamente (GET, POST, PUT, DELETE) e passa a explorar códigos de status HTTP. Muitas APIs REST modernas ficam nesse nível.
Características:
- Métodos alinhados às operações:
- GET /users/123 → obtém usuário.
- POST /users → cria usuário.
- PUT /users/123 → atualiza usuário.
- DELETE /users/123 → remove usuário.
- Uso de códigos HTTP (200, 201, 404, 400 etc.).
- URIs representam recursos, não ações.
Exemplo:

GET /books/1 retorna um livro com status 200 OK.

POST /books cria um novo livro e retorna 201 Created.
Benefício: Maior clareza, interoperabilidade e aderência ao protocolo.
Limitação: Ainda não fornece navegação entre recursos.

Nível 3 – HATEOAS (Hypermedia as the Engine of Application State)

Descrição: O topo da maturidade REST. A API oferece links nas respostas para guiar o cliente na interação com outros recursos. Assim, o cliente descobre as possibilidades de forma dinâmica, como navegamos na web.
Características:
- Respostas incluem links para ações relacionadas.
- Cliente não precisa conhecer URIs fixas.
- A API conduz a navegação via hipermídia.
Exemplo:

  {
    "id": 123,
    "name": "John",
    "_links": {
      "self": { "href": "/users/123" },
      "orders": { "href": "/users/123/orders" },
      "delete": { "href": "/users/123", "method": "DELETE" }
    }
  }

Benefício: Máxima flexibilidade, descoberta de funcionalidades e resiliência a mudanças.
Limitação: Complexo de implementar e muitas vezes desnecessário em APIs simples.

Resumo dos Níveis

Nível 0 → HTTP como transporte, sem recursos nem métodos (RPC-like).
Nível 1 → Recursos com URIs, mas uso limitado do HTTP.
Nível 2 → Métodos e códigos HTTP corretos (padrão mais comum).
Nível 3 → HATEOAS e navegação dinâmica.

Observações

Nível 2 atende à maioria dos casos: Embora o Nível 3 seja o ideal para APIs realmente autodescritivas, ele é mais complexo e raramente essencial.
Use como guia, não como regra: O nível ideal depende do projeto, prazos e objetivos.

📚 Saiba mais: Richardson Maturity Model – Martin Fowler