O que são HATEOAS e o Richardson Maturity Model?

Question

IT Interview Practice · Accepted Answer

O **Richardson Maturity Model (RMM)** classifica quão "RESTful" uma API é ao longo de quatro níveis, e o **HATEOAS** é o nível mais alto — a constraint que a maioria pula.

## Os quatro níveis

```text
Nível 0 — "O Pântano do POX": uma URI, um método (RPC sobre HTTP).
          POST /api  { "action": "getUser", "id": 42 }
Nível 1 — Resources: muitas URIs, mas ainda um verbo.
          POST /users/42  ,  POST /users/42/delete
Nível 2 — HTTP Verbs: métodos + status codes apropriados (onde vive a maioria das "REST" APIs).
          GET /users/42 → 200 ,  DELETE /users/42 → 204
Nível 3 — Hypermedia Controls (HATEOAS): as responses linkam para o que você pode fazer em seguida.
```

A maioria das APIs "REST" em produção está no **Nível 2** — resources, métodos, e status codes corretos. Isso geralmente é bom o suficiente, e é um alvo perfeitamente razoável.

## HATEOAS (Nível 3)

**HATEOAS** = *Hypermedia As The Engine Of Application State*. A ideia: uma response inclui **links** dizendo ao client quais ações estão disponíveis em seguida, então o client navega pela API seguindo links em vez de hardcodar URLs — como um humano seguindo links em uma página web em vez de memorizar cada URL.

```http
GET /orders/1001 HTTP/1.1
```
```http
HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 1001,
  "status": "pending",
  "total": 250,
  "_links": {
    "self":   { "href": "/orders/1001" },
    "pay":    { "href": "/orders/1001/payment", "method": "POST" },
    "cancel": { "href": "/orders/1001/cancel",  "method": "POST" }
  }
}
```

Como o order está `pending`, o server oferece os links `pay` e `cancel`. Uma vez pago, esses links desaparecem e um link `refund` pode aparecer — **o server dirige as transições de estado**, e o client apenas segue quaisquer links que recebe.

## Por que é raro

A promessa é o desacoplamento: os clients não hardcodam URLs, então o server pode reestruturá-las livremente. Na prática a maioria dos clients hardcoda de qualquer forma, o HATEOAS adiciona complexidade real, e os formatos nunca se padronizaram plenamente (HAL, JSON:API, Siren todos competem). O retorno raramente justifica o custo.

## Por que isso importa

Esta é uma pergunta clássica de nível senior porque separa quem **entende REST como originalmente definido** de quem usa "REST" de forma solta para significar "JSON sobre HTTP". O insight valioso não é recitar os quatro níveis — é o discernimento de dizer que o **Nível 2 é o ponto ideal pragmático** enquanto se sabe que o REST verdadeiro (a definição de Fielding) *exige* HATEOAS, e ser capaz de explicar *por que a indústria em grande parte o ignora*: o benefício de desacoplamento é real mas raramente realizado porque os clients hardcodam URLs de qualquer jeito, e a complexidade adicional mais os formatos de hypermedia concorrentes não compensam para APIs típicas. Demonstrar que você sabe o que o HATEOAS *é*, conseguir mostrar um exemplo concreto de links dirigidos por estado, e conseguir argumentar honestamente sobre o custo/benefício — em vez de insistir dogmaticamente que toda API deve ser Nível 3 — é exatamente o discernimento equilibrado e baseado em experiência que os entrevistadores estão sondando.

Os quatro níveis

HATEOAS (Nível 3)

Por que é raro

Por que isso importa

Perguntas relacionadas