Processo de Especificação de API¶

Documento de Referência de Processo¶

Versão: 1.0 Escopo: Define o processo de Especificação de API a ser executado dentro da Fase de Design, após a conclusão dos processos de Engenharia de Requisitos e Arquitetura de Software.

1. Objetivo¶

Este documento define como estruturar, documentar e manter os Contratos de API de um projeto, com nomenclatura e regras de rastreabilidade consistentes com os processos de Requisitos, Arquitetura e Modelagem de Dados já definidos.

2. Processo (passo a passo)¶

2.1 Passo 1 — Identificar o Requisito/Caso de Uso de origem¶

Todo endpoint deve ser rastreável a um RF-000, UC-000 ou ADR-000 — nunca criado “porque parecia útil”.

2.2 Passo 2 — Definir o contrato (request/response)¶

Especificar método HTTP, path, parâmetros, corpo da requisição e todas as respostas relevantes (sucesso e erros esperados).

2.3 Passo 3 — Registrar decisões de design de API não óbvias como ADR¶

Escolhas que fogem do padrão do resto da API merecem um ADR-000 (ex: por que este endpoint é assíncrono/202 quando os outros são síncronos/200).

## ADR-007

- **Decisão:** Endpoint de notificação retorna 202 (Accepted), não 200
- **`<` Backward:** RF-020, ADR-003 (fila assíncrona)
- **Por quê:** Envio real acontece de forma assíncrona via fila — 202 reflete que a requisição foi aceita, não que o processamento terminou
- **Trade-off:** Cliente precisa consultar status separadamente (GET /notificacoes/:jobId/status)
- **`>` Forward:** 02-Contratos-API.md (POST /consultas/:id/notificar)

O Forward de um endpoint pode apontar para mais de uma TASK-000, e essas tasks podem ter naturezas diferentes — uma implementa a rota, outra a consome.

2.4 Passo 4 — Escrever o contrato antes do código (contract-first)¶

O contrato serve de guia para a implementação — qualquer TASK-000 relacionada ao endpoint (seja ela implementando a rota ou consumindo-a) só começa depois do endpoint estar especificado aqui.

2.5 Passo 5 — Manter sincronizado com a implementação¶

Toda mudança de comportamento de um endpoint (novo campo, novo código de erro) atualiza este documento no mesmo commit da mudança de código.

3. Nomenclatura¶

Elemento	Formato	Exemplo
Endpoint	`MÉTODO /caminho` (sem prefixo numérico — o path já identifica)	`POST /auth/login`
Decisão de design de API (quando não óbvia)	`ADR-000` (reaproveita numeração de Arquitetura)	ADR-007
Código de erro	`SNAKE_CASE` descritivo	`AUTH_INVALID`, `CONSULTA_NOT_FOUND`
Task relacionada ao endpoint	`TASK-000` (já documentado em `06-Tasks.md`, do processo de ER — sem subtipo formal, ver seção 6)	TASK-095

4. Convenções gerais¶

- **Base URL:** /api/v1
- **Autenticação:** Bearer Token (JWT), exceto onde marcado como público
- **Formato:** JSON (Content-Type: application/json)
- **Erros seguem o padrão:** { “erro”: string, “codigo”: string }
- **Paginação:** ?page=1&limit=20
- **Datas:** ISO 8601 (UTC)

Essas convenções ficam registradas uma única vez no topo do documento — cada endpoint individual não precisa repeti-las.

5. Template de endpoint¶

MÉTODO /caminho/:parametro¶

< Backward: [RF-000, UC-000, US-000]

Autenticação: [Requerida | Não requerida]

Path params: [se houver]

Request:

{}

Response 2XX:

{}

Response 4XX/5XX:

{
    "erro": "...",
    "codigo": "..."
}

Notas de segurança/observabilidade, se relevantes

> Forward: TASK-000

8. Regra de Rastreabilidade Backward/Forward¶

Campo	Símbolo	Pergunta	Aponta para
Backward	`<`	De onde este endpoint veio?	RF/UC/US de origem, ADR relevante
Forward	`>`	Quais Tasks se relacionam com este endpoint?	Uma ou mais `TASK-000`

Cadeia completa (ER + Arquitetura + Design)¶

RF-000 / UC-000 / US-000
        ↓ backward
    ADR-000 (se decisão de API não óbvia)
        ↓ forward
    Endpoint (MÉTODO /caminho) — contrato explícito
        ↓ forward
    TASK-000 (uma ou mais — implementação e/ou consumo, conforme descrição)
        ↓ forward
    TC-000 (teste)

9. Regra de decisão: quando registrar um ADR de design de API¶

Situação	Precisa de ADR?
Endpoint CRUD simples, seguindo padrão já estabelecido	Não
Código de status HTTP não convencional (ex: 202 em vez de 200)	Sim
Endpoint assíncrono/polling em vez de síncrono	Sim
Mudança incompatível em endpoint já existente (breaking change)	Sim
Escolha entre REST vs. outro estilo (GraphQL, webhook) para um caso específico	Sim

11. Manutenção do documento ao longo do projeto¶

Regra prática:

Novo endpoint → adicionar seção ao documento existente ANTES de codar (contract-first)
Mudança de contrato → atualizar a seção correspondente no mesmo commit da mudança de código
Endpoint removido/depreciado → marcar como “Status: Depreciado” em vez de apagar (mantém histórico de rastreabilidade)
Nova Task que passa a implementar ou consumir um endpoint existente → adicionar seu ID à lista de Forward do endpoint correspondente
Documento nunca fica dessincronizado do comportamento real da API

12. Estrutura de pastas¶

Design/
 02-Contratos-API.md

Assim como o Modelo de Dados, um único arquivo concentra todos os endpoints — organizados por domínio/módulo dentro do mesmo documento (seções ## Autenticação, ## Notificações, ## Prontuário, etc.), não um arquivo por endpoint.

13. Fluxograma Resumido do Processo¶

1. Identificar RF/UC/US de origem
        ↓
2. Especificar contrato (request/response, erros)
        ↓
3. Registrar decisões de API não óbvias como ADR-000
        ↓
4. Escrever contrato ANTES do código (contract-first)
        ↓
5. Registrar TASK-000 no Forward do endpoint (implementação e/ou consumo, conforme a descrição de cada task)
        ↓
6. Manter documento sincronizado a cada mudança

14. Resumo Executivo¶

Rastrear todo endpoint a um RF-000/UC-000/US-000 de origem
Especificar contract-first: request, response de sucesso, respostas de erro
Registrar decisões de design de API não óbvias como ADR-000
Apontar o Forward para uma ou mais TASK-000 — sem subtipo formal; a descrição de cada task já indica se ela implementa ou consome a rota
Manter um único documento por projeto, organizado por domínio, sempre sincronizado com o código