IMP — API Contract (B)

O que é

Ponto de vista: IMP — Implementação · Pasta típica: IMP (Implementação)/03-decisoes/

O API Contract especifica um endpoint (REST, gRPC ou GraphQL) derivado de histórias de integração (ESP-HI) ou de serviço (ESP-HS). Funciona como contrato formal entre o fornecedor e o consumidor da API.

Como usar

Só formalize o contrato após a história de origem estar aprovada (HI/HS).
Versione alterações com SemVer quando o contrato estiver publicado.
Alinhe com TDD da mesma história quando existir desenho técnico.

Exemplo

---
id: IMP-API-0001
tipo: API
titulo: "Contrato — Endpoint de autenticação"
status: rascunho
autor: fulano.de.tal
data: 2026-04-11
historia-origem: ESP-HI-0001
versao: "1.0"
base-url: "/api/v1"
protocolo: REST
formato: JSON
---

endpoints:
  - path: "/auth/login"
    method: POST
    descricao: "Autentica usuário via gov.br"
    request:
      body:
        code: string
        state: string
    response:
      200:
        token: string
        expira-em: integer
      401:
        mensagem: string

Onde se aplica

Destino	Link
Framework IMP	/framework/imp/
Índice IMP	/artefatos/imp/
HI / HS (ESP)	/artefatos/esp/hi/ · /artefatos/esp/hs/
TDD	/artefatos/imp/tdd/

Regras

O API Contract é vinculado à história ESP que o originou — a história de integração deve estar aprovada antes de se escrever o contrato.
Toda mudança de contrato em estado publicado requer nova versão (SemVer) e comunicação ao IMP e ao GTI.
Contratos rejeitados pelo time de revisão são mantidos como cancelado para rastreabilidade.
Protocolos suportados: REST, gRPC, GraphQL, SOAP.

← TDD · DOD →