As APIs REST Devem Implementar Links de Hipermídia HATEOAS?

Resumo

HATEOAS (Hypermedia as the Engine of Application State) é teoricamente elegante, mas praticamente complexo. A maioria das APIs ignora o HATEOAS completo e usa links de hipermídia seletivos para paginação, recursos relacionados e ações. A Modern PetstoreAPI implementa links de hipermídia práticos sem forçar os clientes a serem totalmente orientados por hipermídia.

Introdução

Você está lendo sobre design de API REST. Você encontra o HATEOAS (Hypermedia as the Engine of Application State). A explicação diz: "Os clientes devem descobrir todas as ações através de links de hipermídia, e não por URLs codificadas."

Você pensa: "Isso parece complicado. Alguém realmente faz isso?"

A resposta: na verdade, não. HATEOAS é a restrição REST mais ignorada. Roy Fielding (que inventou o REST) diz que é essencial. A maioria dos designers de API diz que é impraticável. O resultado: a maioria das APIs "REST" não são verdadeiramente RESTful de acordo com a definição de Fielding.

A Modern PetstoreAPI adota uma abordagem pragmática: usar links de hipermídia onde agregam valor (paginação, recursos relacionados, ações), mas sem forçar os clientes a serem totalmente orientados por hipermídia.

💡

Se você está construindo ou testando APIs REST, o Apidog te ajuda a testar links de hipermídia, validar formatos de links e garantir que sua API forneça uma navegação útil. Você pode verificar a correção dos links e testar fluxos de trabalho orientados por hipermídia.

botão

Neste guia, você aprenderá o que é HATEOAS, por que é controverso e como implementar links de hipermídia práticos usando a Modern PetstoreAPI como referência.

O Que É HATEOAS?

HATEOAS é uma restrição REST que diz que os clientes devem descobrir as capacidades da API através de links de hipermídia, e não por documentação.

O Conceito

Em vez de codificar URLs:

// O cliente codifica URLs
const response = await fetch('https://petstoreapi.com/v1/pets/123');
const pet = await response.json();

// O cliente conhece a estrutura da URL
await fetch(`https://petstoreapi.com/v1/pets/${pet.id}/orders`);

Os clientes seguem links das respostas:

// O cliente começa na raiz
const root = await fetch('https://petstoreapi.com/v1');
const rootData = await root.json();

// O cliente segue o link para pets
const petsUrl = rootData._links.pets.href;
const pets = await fetch(petsUrl);
const petsData = await pets.json();

// O cliente segue o link para um pet específico
const petUrl = petsData._links.self.href;
const pet = await fetch(petUrl);
const petData = await pet.json();

// O cliente segue o link para orders
const ordersUrl = petData._links.orders.href;
const orders = await fetch(ordersUrl);

A Teoria

Com HATEOAS:

1. Os clientes não codificam URLs

As URLs podem mudar sem quebrar os clientes. O servidor controla a estrutura das URLs.

2. Os clientes descobrem capacidades

Se um link existe, a ação está disponível. Se não, não está disponível (ou não é permitida para este usuário).

3. As APIs são auto-documentadas

Os clientes exploram a API seguindo links, como navegar em um site.

Exemplo: Resposta HATEOAS Completa

{
  "id": "019b4132-70aa-764f-b315-e2803d882a24",
  "name": "Fluffy",
  "species": "CAT",
  "status": "AVAILABLE",
  "_links": {
    "self": {
      "href": "https://petstoreapi.com/v1/pets/019b4132-70aa-764f-b315-e2803d882a24"
    },
    "update": {
      "href": "https://petstoreapi.com/v1/pets/019b4132-70aa-764f-b315-e2803d882a24",
      "method": "PUT"
    },
    "delete": {
      "href": "https://petstoreapi.com/v1/pets/019b4132-70aa-764f-b315-e2803d882a24",
      "method": "DELETE"
    },
    "orders": {
      "href": "https://petstoreapi.com/v1/pets/019b4132-70aa-764f-b315-e2803d882a24/orders"
    },
    "adopt": {
      "href": "https://petstoreapi.com/v1/pets/019b4132-70aa-764f-b315-e2803d882a24/adopt",
      "method": "POST"
    }
  }
}

O cliente não precisa saber os padrões de URL. Ele segue os links.

O Debate HATEOAS

HATEOAS é controverso porque a teoria e a prática divergem.

Argumentos A Favor do HATEOAS

1. Acoplamento fraco

Os clientes não dependem da estrutura da URL. O servidor pode alterar as URLs sem quebrar os clientes.

2. Descoberta

Os clientes podem explorar a API sem ler a documentação.

3. Ações orientadas por estado

Os links mostram quais ações estão disponíveis. Se um animal de estimação for adotado, o link "adopt" desaparece.

4. REST Verdadeiro

Roy Fielding diz que HATEOAS é essencial para REST. Sem ele, você não está fazendo REST.

Argumentos Contra o HATEOAS

1. Complexidade

Os clientes precisam de lógica de análise de hipermídia. Clientes HTTP simples tornam-se máquinas de estado complexas.

2. Performance

Os clientes fazem múltiplas requisições para descobrir URLs. O acesso direto à URL é mais rápido.

3. Dificuldade de depuração

Seguir links dificulta a depuração. Você não pode simplesmente usar curl em uma URL – você precisa seguir a cadeia de links.

4. Ferramentas deficientes

A maioria dos clientes HTTP, ferramentas de teste e geradores de documentação assume URLs codificadas.

5. Ninguém faz isso

GitHub, Stripe, Twilio, Twitter — as principais APIs não usam o HATEOAS completo. Se eles não precisam, você precisa?

A Realidade

A maioria das APIs afirma ser "REST" mas ignora o HATEOAS. Na verdade, são "APIs HTTP" ou "APIs semelhantes a REST". O REST verdadeiro (com HATEOAS) é raro.

Links de Hipermídia Práticos

Em vez de HATEOAS completo, use links de hipermídia onde eles agregam valor.

1. Links de Paginação

Problema: Os clientes precisam construir URLs de paginação.

Solução: Fornecer links de próximo/anterior.

{
  "data": [...],
  "pagination": {
    "page": 2,
    "limit": 20,
    "totalPages": 10
  },
  "links": {
    "self": "https://petstoreapi.com/v1/pets?page=2&limit=20",
    "first": "https://petstoreapi.com/v1/pets?page=1&limit=20",
    "prev": "https://petstoreapi.com/v1/pets?page=1&limit=20",
    "next": "https://petstoreapi.com/v1/pets?page=3&limit=20",
    "last": "https://petstoreapi.com/v1/pets?page=10&limit=20"
  }
}

Benefício: Os clientes não constroem URLs de paginação. Eles seguem os links.

2. Links de Recursos Relacionados

Problema: Os clientes precisam conhecer os padrões de URL para recursos relacionados.

Solução: Fornecer links para recursos relacionados.

{
  "id": "019b4132-70aa-764f-b315-e2803d882a24",
  "name": "Fluffy",
  "_links": {
    "self": "https://petstoreapi.com/v1/pets/019b4132-70aa-764f-b315-e2803d882a24",
    "orders": "https://petstoreapi.com/v1/pets/019b4132-70aa-764f-b315-e2803d882a24/orders",
    "owner": "https://petstoreapi.com/v1/users/019b4127-54d5-76d9-b626-0d4c7bfce5b6"
  }
}

Benefício: Os clientes descobrem recursos relacionados sem documentação.

3. Links de Ação

Problema: Os clientes precisam saber quais ações estão disponíveis.

Solução: Fornecer links para as ações disponíveis.

{
  "id": "019b4132-70aa-764f-b315-e2803d882a24",
  "status": "AVAILABLE",
  "_links": {
    "adopt": {
      "href": "https://petstoreapi.com/v1/pets/019b4132-70aa-764f-b315-e2803d882a24/adopt",
      "method": "POST"
    }
  }
}

Se o animal de estimação já foi adotado:

{
  "id": "019b4132-70aa-764f-b315-e2803d882a24",
  "status": "ADOPTED",
  "_links": {
    // Sem link "adopt" - ação não disponível
  }
}

Benefício: Os links indicam as ações disponíveis com base no estado.

4. Paginação Baseada em Cursor

Problema: Os clientes precisam construir URLs de cursor.

Solução: Fornecer URLs opacas de próximo/anterior.

{
  "data": [...],
  "links": {
    "next": "https://petstoreapi.com/v1/pets?cursor=eyJpZCI6IjAxOWI0MTMyIn0"
  }
}

Benefício: Os clientes não analisam cursores. Eles seguem os links.

Como a Modern PetstoreAPI Usa Hipermídia

A Modern PetstoreAPI usa links de hipermídia seletivos.

Links de Paginação

Todos os endpoints de coleção incluem links de paginação:

GET /v1/pets?limit=20

{
  "data": [...],
  "pagination": {
    "limit": 20,
    "hasMore": true
  },
  "links": {
    "self": "https://petstoreapi.com/v1/pets?limit=20",
    "next": "https://petstoreapi.com/v1/pets?cursor=eyJpZCI6IjAxOWI0MTMyIn0&limit=20"
  }
}

Links de Recursos Relacionados

As respostas de recurso incluem links para recursos relacionados:

GET /v1/pets/019b4132-70aa-764f-b315-e2803d882a24

{
  "id": "019b4132-70aa-764f-b315-e2803d882a24",
  "name": "Fluffy",
  "ownerId": "019b4127-54d5-76d9-b626-0d4c7bfce5b6",
  "_links": {
    "self": "https://petstoreapi.com/v1/pets/019b4132-70aa-764f-b315-e2803d882a24",
    "owner": "https://petstoreapi.com/v1/users/019b4127-54d5-76d9-b626-0d4c7bfce5b6",
    "orders": "https://petstoreapi.com/v1/pets/019b4132-70aa-764f-b315-e2803d882a24/orders"
  }
}

Sem HATEOAS Completo

A Modern PetstoreAPI não exige que os clientes sejam orientados por hipermídia. Os clientes podem:

Opção 1: Seguir links (orientado por hipermídia)

const pet = await fetch(petUrl);
const ownerUrl = pet._links.owner.href;
const owner = await fetch(ownerUrl);

Opção 2: Construir URLs (tradicional)

const pet = await fetch(`https://petstoreapi.com/v1/pets/${petId}`);
const owner = await fetch(`https://petstoreapi.com/v1/users/${pet.ownerId}`);

Ambas as abordagens funcionam. Os links são fornecidos por conveniência, não por imposição.

Testando APIs de Hipermídia com Apidog

O Apidog te ajuda a testar links de hipermídia e a validar a correção dos links.

Testar Presença de Link

Verifique se as respostas incluem os links esperados:

// Script de teste Apidog
pm.test("A resposta inclui links de paginação", () => {
  const links = pm.response.json().links;
  pm.expect(links).to.have.property('self');
  pm.expect(links).to.have.property('next');
});

Testar Validade do Link

Siga os links e verifique se funcionam:

// Script de teste Apidog
const nextUrl = pm.response.json().links.next;

pm.sendRequest(nextUrl, (err, response) => {
  pm.test("O próximo link retorna 200", () => {
    pm.expect(response.code).to.equal(200);
  });
});

Testar Formato do Link

Verifique se os links seguem o formato esperado:

pm.test("Os links são URLs absolutas", () => {
  const links = pm.response.json().links;
  Object.values(links).forEach(link => {
    pm.expect(link).to.match(/^https:\/\//);
  });
});

Quando Usar HATEOAS

Use links de hipermídia quando eles agregam valor. Ignore-os quando não agregam.

Use Links de Hipermídia Para:

1. Paginação - Os clientes não devem construir URLs de paginação

2. Recursos relacionados - Navegação conveniente

3. Ações dependentes de estado - Mostre as ações disponíveis com base no estado do recurso

4. Fluxos de trabalho complexos - Guie os clientes através de processos multi-etapas

Ignore HATEOAS Para:

1. APIs CRUD simples - Os clientes podem construir URLs facilmente

2. APIs Internas - Equipes podem coordenar mudanças de URL

3. APIs críticas para performance - Links extras aumentam o tamanho da resposta

4. APIs Móveis - A largura de banda importa, links adicionam sobrecarga

Conclusão

HATEOAS é teoricamente elegante, mas praticamente complexo. A maioria das APIs ignora o HATEOAS completo e usa links de hipermídia seletivos onde eles agregam valor.

A Modern PetstoreAPI demonstra hipermídia prática: links de paginação, links de recursos relacionados e links de ação — sem forçar os clientes a serem totalmente orientados por hipermídia.

Use o Apidog para testar links de hipermídia, validar a correção dos links e garantir que sua API forneça uma navegação útil.

Principais aprendizados:

HATEOAS completo é raro e complexo
Links de hipermídia seletivos agregam valor sem complexidade
Links de paginação são o recurso de hipermídia mais útil
Não force os clientes a serem orientados por hipermídia
Teste os links para garantir que funcionem corretamente

Explore a documentação da Modern PetstoreAPI para ver a implementação prática de hipermídia.

botão

Perguntas Frequentes

HATEOAS é necessário para APIs REST?

De acordo com Roy Fielding (inventor do REST), sim. Na prática, não. A maioria das APIs "REST" ignora o HATEOAS e são tecnicamente "APIs HTTP" ou "APIs semelhantes a REST".

O que significa HATEOAS?

Hypermedia as the Engine of Application State (Hipermídia como o Motor do Estado da Aplicação). Significa que os clientes descobrem as capacidades da API através de links de hipermídia, e não por URLs codificadas.

As principais APIs usam HATEOAS?

Não. GitHub, Stripe, Twilio e a maioria das principais APIs não usam o HATEOAS completo. Elas podem incluir alguns links de hipermídia (paginação, recursos relacionados), mas não exigem que os clientes sejam orientados por hipermídia.

Qual é a diferença entre HATEOAS e links de hipermídia?

HATEOAS é uma restrição que exige que os clientes sejam totalmente orientados por hipermídia. Links de hipermídia são apenas links em respostas. Você pode incluir links sem impor o HATEOAS.

Devo implementar HATEOAS na minha API?

Provavelmente não o HATEOAS completo. Use links de hipermídia seletivos para paginação e recursos relacionados. Não force os clientes a serem orientados por hipermídia a menos que você tenha um motivo específico.

Como testo APIs HATEOAS?

Use o Apidog para verificar a presença de links, seguir links e validar a correção dos links. Teste se os links retornam as respostas esperadas.

O que é o formato HAL?

HAL (Hypertext Application Language) é um formato padrão para links de hipermídia. Ele usa os campos _links e _embedded. A Modern PetstoreAPI usa um formato de link inspirado em HAL.

Os clientes podem ignorar links de hipermídia?

Sim. Se sua API fornece links, mas não exige que os clientes os usem, os clientes podem construir URLs diretamente. Esta é a abordagem pragmática que a maioria das APIs adota.