Como documentar um endpoint REST de forma clara e objetiva (com exemplo real)

A documentação de uma API REST pode ser a diferença entre um sistema fácil de integrar e um verdadeiro pesadelo. Muitas vezes negligenciada, uma boa documentação economiza tempo, evita retrabalho e melhora a comunicação entre equipes.

Neste post, vou mostrar um modelo direto de como documentar endpoints REST — com base em exemplos reais e cobrindo os principais métodos: GET, POST, PUT, PATCH e DELETE.

---

🧭 Visão geral dos métodos HTTP

---

🧪 Exemplo: API de Consulta de Processos

Vamos usar uma API fictícia chamada /api/processos para ilustrar cada um dos métodos.

---

1. 🔍 GET /api/processos/{id}

Buscar detalhes de um processo específico

📍 URL

GET /api/processos/0001234-56.2023.8.26.0001

🔼 Resposta

{
  "numeroProcesso": "0001234-56.2023.8.26.0001",
  "classe": "Ação Cível",
  "assunto": "Cobrança",
  "dataDistribuicao": "2023-08-15",
  "partes": [
    { "nome": "Maria da Silva", "tipo": "AUTOR" },
    { "nome": "João de Souza", "tipo": "RÉU" }
  ]
}

---

2. 📝 POST /api/processos

Criar um novo processo

📤 Requisição

{
  "numeroProcesso": "0001234-56.2023.8.26.0001",
  "classe": "Ação Cível",
  "assunto": "Cobrança"
}

🔼 Resposta

• 201 Created com o corpo criado ou o ID do recurso

---

3. 🔄 PUT /api/processos/{id}

Atualizar totalmente um processo existente

📤 Requisição

{
  "classe": "Ação Penal",
  "assunto": "Furto qualificado"
}

🔼 Resposta

• 200 OK com os dados atualizados

---

4. 🩹 PATCH /api/processos/{id}

Atualizar parcialmente um processo

📤 Requisição

{
  "assunto": "Atualização cadastral"
}

🔼 Resposta

• 200 OK com os dados atualizados

---

5. 🗑️ DELETE /api/processos/{id}

Remover um processo

📍 URL

DELETE /api/processos/0001234-56.2023.8.26.0001

🔼 Resposta

• 204 No Content

---

🧠 Boas práticas ao documentar endpoints

1. Seja específico: mostre exemplos reais de entrada e saída.

2. Liste os códigos de status possíveis: isso evita dúvidas sobre como tratar a resposta.

3. Explique os métodos: muitos devs confundem PUT e PATCH.

4. Padronize tudo: headers, estrutura dos campos, nomes das rotas.

---

Conclusão

Uma documentação clara é um presente que você dá para o seu "eu do futuro" — e para toda a equipe que vai consumir sua API. Com um modelo bem definido, tudo flui melhor.

---

Curtiu o exemplo? Tem alguma dúvida ou sugestão? Comenta aqui ou me chama no LinkedIn — vou trazer mais conteúdos sobre APIs e práticas reais de backend!