# 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

<table><tbody><tr><td colspan="1" rowspan="1"><p><strong>Método</strong></p></td><td colspan="1" rowspan="1"><p><strong>Finalidade</strong></p></td></tr><tr><td colspan="1" rowspan="1"><p><code>GET</code></p></td><td colspan="1" rowspan="1"><p>Buscar informações</p></td></tr><tr><td colspan="1" rowspan="1"><p><code>POST</code></p></td><td colspan="1" rowspan="1"><p>Criar um novo recurso</p></td></tr><tr><td colspan="1" rowspan="1"><p><code>PUT</code></p></td><td colspan="1" rowspan="1"><p>Atualizar um recurso inteiro</p></td></tr><tr><td colspan="1" rowspan="1"><p><code>PATCH</code></p></td><td colspan="1" rowspan="1"><p>Atualizar parcialmente um recurso</p></td></tr><tr><td colspan="1" rowspan="1"><p><code>DELETE</code></p></td><td colspan="1" rowspan="1"><p>Remover um recurso</p></td></tr></tbody></table>

---

## 🧪 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

```json
{
  "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

```json
{
  "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

```json
{
  "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

```json
{
  "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!**