Pular para conteúdo

Template: API

Objetivo

Padronizar a documentação de rotas — tanto URLs Django server-rendered quanto endpoints DRF, conforme o que o módulo real tem.

Módulo sem API REST própria (maioria dos módulos hoje)

Usar uma tabela simples de rotas Django, como no exemplo real de Accounts:

# Interfaces e rotas

Não existe API REST própria do módulo `<modulo>`. A interface é composta por URLs Django em `apps/<modulo>/urls.py`:

| Rota | Nome | Comportamento |
|---|---|---|
| `/<rota>/` | `<modulo>:<nome>` | O que a rota faz |

Módulo com API REST (DRF)

# API

Base: `/api/v1/<recurso>/`

## `GET /api/v1/<recurso>/`

Lista `<Recurso>`, paginado (`paginate_by = 10`).

**Autenticação:** obrigatória. **Permissão:** `<permissão real>`.

### Resposta 200

​```json
{
  "success": true,
  "data": {"results": [], "count": 0},
  "errors": [],
  "message": ""
}
​```

## `POST /api/v1/<recurso>/`

Cria `<Recurso>`. Gera log de auditoria (ação 4 — Inclusão).

### Corpo da requisição

| Campo | Tipo | Obrigatório |
|---|---|---|
| ... | ... | ... |

### Erros possíveis

| Código | Motivo |
|---|---|
| 400 | Validação falhou |
| 403 | Sem permissão |

Regra de preenchimento

Verificar urls.py/api/urls.py e api/viewsets.py/api/serializers.py reais antes de escrever — nunca documentar uma rota que não existe no código, nem inventar um formato de resposta diferente do padrão real (success/data/errors/message, ver Backend Standard).

Referências