Contratos de API v0.1 Candidato ao G2 · sem backend

Contratos das APIs

Do clique ao evento, cada fronteira explica método, intenção, versão, falha e rastro. É um contrato pronto para implementação — não uma promessa de serviço já ligado.

OpenAPI 3.1 válidoEndpoint ilustrativo .invalid

operações

primeira onda

comandos

idempotentes

consultas

por escopo

endpoints vivos

produção preservada

Catálogo executável

13 fronteiras

13 visíveis

POSTAdesão e ativaçãoComando

Ativar adesão

/api/v1/memberships/{id}/activations

Ativa uma única vez, somente online, congelando as versões usadas na decisão.

Requisiçãoapplication/json

POST /api/v1/memberships/{id}/activations
Idempotency-Key: idem_demo_01HXF
X-Correlation-Id: corr_demo_01HXF

{
  "data": {
    "readiness_evaluation_ref": "ready_demo_01",
    "effective_on": "2026-09-04"
  },
  "expected_version": 5
}

Resposta simulada201 · Sucesso

{
  "resource_id": "membership_demo_01",
  "status": "ATIVA",
  "processing_state": "processed",
  "version": 6,
  "correlation_id": "corr_demo_008"
}

Teste a forma do contrato

A validação é local e não envia dados nem chama um backend.

Rastreabilidade

Efeito e requisitos

Evento relacionado

membership.activated

ATI-001ATI-006ATI-007ATI-008

Proteções

O que esta fronteira garante

Repetição protegida por Idempotency-Key

Correlação devolvida em sucesso e falha

Confirmação depende de conexão com o servidor

G2 pendente

Protocolo de confiança

Cinco garantias que atravessam as 13 operações.

Um comando, um efeito

Todo POST exige Idempotency-Key e devolve o mesmo resultado quando a mesma intenção é repetida.

Rastro ponta a ponta

X-Correlation-Id acompanha chamada, mudança de estado, evento, integração e erro.

Versão protegida

expected_version impede que uma decisão sobrescreva outra feita sobre estado mais recente.

Falha explicável

Erros seguem application/problem+json, com código estável, correlação, ação sugerida e possibilidade de nova tentativa.

Sem falso sucesso offline

Uma captura local pode ficar pendente; ativação e efeitos finais nunca são prometidos sem confirmação do servidor.

Limite consciente

O contrato define a forma da conversa. Banco provisionado, autenticação, regras homologadas, filas, integrações e observabilidade ainda precisam ser implementados.

Produção permanece em 0%

Failure design

Toda falha chega com uma próxima ação.

Cinco classes estáveis para produto, suporte, backend e observabilidade falarem a mesma língua.

application/problem+json

HTTP 403

Acesso negado

AUTHORIZATION_DENIED

Revisar perfil, escopo e segregação sem revelar o registro protegido.

Exige correção ou decisão

HTTP 409

Versão desatualizada

VERSION_CONFLICT

Recarregar o estado vigente antes de reaplicar a decisão.

Exige correção ou decisão

HTTP 422

Pré-condição não satisfeita

RULE_VIOLATION

Exibir bloqueios e a próxima ação autorizada.

Exige correção ou decisão

HTTP 409

Chave já usada com outra intenção

IDEMPOTENCY_CONFLICT

Não repetir o efeito; gerar nova chave somente para uma nova intenção.

Exige correção ou decisão

HTTP 503

Dependência temporariamente indisponível

DEPENDENCY_UNAVAILABLE

Preservar a operação e retomar com backoff, sem duplicar.

Retentativa controlada

Próxima etapa: implementar os serviços.

Fechar G1/G2, escolher identidade e banco, implementar a primeira cadeia de comandos com outbox e provar os cenários de duplicidade, concorrência, falha e recuperação.

Abrir primeira onda

Ir para uma área

Contratos das APIs

Ativar adesão

Toda falha chega com uma próxima ação.

Próxima etapa: implementar os serviços.