Protocol-first design

O que é Protocol-first

Protocol-first é uma abordagem em que o contrato de interação entre componentes (serviços, clientes, parceiros externos) é projetado e fixado antes da implementação. Código, armazenamento, infraestrutura e documentação obedecem ao contrato e são gerados automaticamente a partir dele, e não o contrário.

Ao contrário do «código-first», onde a API é apenas um subproduto do código, o Protocol-First faz do protocolo um artefacto primário: possui noções de domínio, modelos de dados, estatais, erros, semântica de idempotidade, SLO/SLI e até políticas de versões.

Para quê?

Coerência e previsibilidade das interfaces em escala de organização.
Acerto rápido (SDK/Stubs/clientes, erros e códigos unificados).
Evolução confiável (compatibilidade de circuitos, contratações-teste, políticas de versões claras).
Foco de alimentos: discutindo comportamento, SLA e X integração antes de escrever o código.
Automação: CI/CD recolhe artefatos (clientes, barras de servidores, validadores) de uma única fonte de verdade.
Segurança e compliance: direitos, camuflagem PII, políticas de reticência são estabelecidas no contrato.

Núcleo de aproximação

1. Uma única fonte de verdade (SSOT) - especificações legíveis por máquina:

REST: OpenAPI/JSON Schema.
Eventos e streaming: Avro/JSON Schema.
RPC: Protobuf (gRPC), Thrift, Smithy.
GraphQL: SDL + diretrizes/políticas.
2. Acordos anteriores à implementação: glossário de domínio, códigos de erro, semântica de idempotidade, dedline, retraí, dedução.
3. Geração automática: clientes/servidores, tipos, SDK, contratos-teste, moki, colecção Postman, Terraform/OpenAPI Gateway-config.
4. Governance: Linters/Políticas (naming, paginação, filtros, erros), review através da API guild, mudança-advisory para versões maiores.
5. Compatibilidade: verificação rigorosa de difs «aditive-only», versionagem semântica, testes canary/consumer-driven.
6. Observabilidade ao nível do contrato: ID de correlação, modelos de erro, orçamentos de atrasos são definidos no protocolo.

Como é o processo (esqueleto)

1. Iniciação: brife de alimentos → user journal → API/Protocol PRD (recursos/métodos/eventos, SLA/SLO, erros, limites).
2. Simulação: rascunho de especificação (OpenAPI/AsyncAPI/Proto) + padrão de dados, dicionário de termos.
3. Contratos e integração UX: exemplos de carga útil, contratos de erro, mapas de estatais, regras de versionização.
4. Revezamento e governance: linterners/padrões, discussão de invariantes de domínio, lock-in MGC (contrato mínimo de garantia).
5. Geração automática de artefatos: SDK, manadas, ficstures de teste, infra-estruturas (Gateways, IAM scopes).
6. Implementação e testes contratuais: O fornecedor e os consumidores estão sujeitos a testes de compatibilidade em CI.
7. Observabilidade e SLO: rastreamento por correlation-id, erro catalog, orçamentos de retrações/temporizações.
8. Lançamentos e evolução: aditiva-first, deprecation policy, canary, A/B capability flags.

Protocolos e estilos de interação

REST/HTTP

Padrões: modelo de recursos, 'GET/POST/PATCH/DELETE', paginação (cursor), filtros, triagem.
Campos e esquemas: JSON Schema, formatos ('data-time', 'uuid'), invariantes (regex/enum/min-max).
Erro: formato único («tipo», «código», «title», «detail», «trace _ id»), mapping na pilha HTTP.
Controle de alterações: ETag/If-Match, chaves idumpotentes para POST, semânticos expressos 409/422.

gRPC/RPC

Protobuf: numeração estável de marcas de formatação, 'optional', impedindo reutilização de campos remotos.
Deadlines e prioridades no contrato; estatais estáveis (OK, INVALID _ ARGUMENT, FAILED _ PRECISION, etc.).
Streaming: especificação de ordem de mensagens, backpressure, trailers finais.

Event-driven (Kafka/NATS/SNS/SQS)

AsyncAPI: tópicos/canais, chaves de partilha, acordos de dedução, reticência, semântica «exatamente uma vez» vs «pelo menos uma vez».
Evento-núcleo e enriquecimento: divida o payload mínimo e as extensões; versionalize 'event _ tipo '/' schema _ versão'.
Idempotidade: 'event _ id', 'producer _ id', 'policy' em retratos e dedução.

GraphQL

SDL como contrato, diretrizes para depredação, limites de profundidade e complexidade, contrato de erro (error codes/extensões).

Integração com princípios arquitetônicos

Investe Pyramid/Critical Path First: Na especificação, atribuir MGC (mínimo obrigatório) e extensões através de '? inclusive = '/capabilities.
Paved Roads: conjunto de padrões de especificação prontos (payment, KYC, auditório, search, files) + lentes.
API Gateways & Service Mesh: Políticas baseadas em contrato (rate-limits, autoescopes, retries, circuito-breakers).

Versionização e evolução

• Menor = apenas campos/canais aditivos.
• Major = alterações quebrantes (remoções, renomeações, alterações semânticas).
• Deprecation Policy: janelas de suporte, cabeçalhos «Sunset», eventos de notificação.
• Consumer-Driven Contracts (CDC): Verificamos que a API atual atende a consumidores específicos.
• Catálogo de diagramas: Registro (Schema Registry/Artifact Registry) com histórico e regras de compatibilidade (BACKWARD/FORWARD/FULL).

Segurança e Complacência

Autenticação/autorização como parte do contrato (OAuth2/OIDC scopes, mTLS, JWT clims).
PII/PCI: camuflagem, formatos de torneamento, campos com modos especiais de armazenamento/TTL.
Políticas de auditoria: atributos obrigatórios ('ator', 'subject', 'action', 'accurred _ at', 'trace _ id').
Limites: rate limit headers, quotas, tamanho de mensagens, deadline.

Observabilidade contratual

Correlation/Request-ID: obrigatório na especificação.
Error Catalog: lista fixa de códigos e SLA de eliminação.
SLI/SLO: p50/p95 latency, proporção de respostas bem sucedidas, proporção de eventos compatíveis, proporção de repetições idumpotentes.

Testes e qualidade

Contracto tets (fornecedor ↔ consumidor), schema diff em CI, geração de servidores MK.
Golden sample: exemplos de referência de pedidos/respostas, ficstoors para e2e.
Chaos/latency inhation: verificação de temporizações/retrações, degradação de extensões com MGC.

Modelos de domínio

Pagamento (REST+ eventos)

«POST/payments» (chave idumpotente) → '201 Created' s 'payment _ id', 'status = autorized'.
Evento 'payment. authorized. v1` (ядро): `{ payment_id, amount, currency, method, occurred_at }`.
Extensão 'payment. enriched. v1: risco-screen, geo, device-fingerprint.
Erros: '422' (validação), '402' (payment required), '409' (duplicado).
SLA: autorização ≤ 800ms p95; evento de núcleo ≤ 2s lag p95.

KYC (gRPC + filas)

RPC `StartVerification(user_id)` → `operation_id`.
Eventos de progresso no topic 'kyc. status. v1` (`PENDING` → `APPROVED/REJECTED`).
O contrato especifica campos PII, prazo de armazenamento, camuflagem, códigos de falha.

Auditoria (Event-only)

`audit. recorded. v1` (ядро): `actor`, `subject`, `action`, `occurred_at`, `trace_id`.
Enriquecimento: IP, device, geo - evento/fluxo individual, não bloqueia o núcleo.

Ferramentas e automação (amostra)

Спеки: OpenAPI/AsyncAPI/Protobuf/Avro/GraphQL SDL.
Линтеры: Spectral, OpenAPI Diff, Buf (protobuf), Confluent SR compatibility checks.
Генерация: OpenAPI Generator, Buf/Protoc, GraphQL Codegen, AsyncAPI Generator.
Gateway: Kong/Apigee/Azure/GCP GW, Envoy.
Тесты: Pact/CDC, Dredd, Schemathesis, Hoverfly, MockServer.
Registro: Catálogo GIT + Schema Registry/Artifact Registry.
Documentação: Redocly/Stoplight/Swagger-UI/GraphiQL/Explorer.

Anti-pattern

«Primeiro MVP nos controladores», especificação pós-faturamento, discrepância de documentação e comportamento.
Swagger-wash: OpenAPI formal sem regras reais (erros, limites, SLA, versões).
Camada de compatibilidade: removeu o campo/alterou o tipo sem a versão maior; reutilização de marcas protobuf.
Resposta «gorda» sem paginação/filtros; Não há idepotência.
Securities fora do contrato: auth/Scopes são descritas em wiki, mas não na especificação.

Relação com a organização do processo

API Guild: administradores de padrões, reviravoltas, treinamento.
Design Docs: para cada API - PRD, ADR (soluções), SLA, matriz de risco.
Mudar Management: Processo RFC, release de notas, guias de migração, deprecation-timeline.
Paved Road & Templates: geradores de esqueletos de serviço a partir de especificação (esqueleto de handlers, validação, loging).

Folhas de cheque

Antes do início

• Há PRD e glossário de domínio.
• O estilo (REST/gRPC/Event/GraphQL) e o formato de padrão foram selecionados.
• Definidos MGC, erros, SLA/SLO, regras de idempotação.

Em desenvolvimento

• A especificação passa por linters e review.
• A geração automática SDK/stubs/ficstur está configurada.
• O contrato-teste (CDC) está incluído na CI; o schema-diff bloqueia alterações incompatíveis.

Antes do lançamento

• Documentação para integradores com exemplos e códigos de erro.
• Observabilidade contratual: correlation-id, erro catalog, dashboard SLI.
• A política de versionalidade e a deprecação foram anunciadas.

FAQ

Em que o Protocol-first difere da API-first?
Muitas vezes os termos são usados como sinônimos. Neste artigo sob Protocol-first, destacamos o rigor do contrato e a abrangência de todos os estilos (incluindo SLA, segurança e observabilidade.

Isso não vai atrasar o desenvolvimento?
O início pode ser um pouco mais longo, mas depois ganhamos com integração, estabilidade e velocidade de desenvolvimento paralelo (geração automática, SDK estável).

O que fazer com as experiências rápidas?
Use versões de esquema «rascunho» (draft), função flags e grampos de areia, mas não perca as lentes e regras básicas de compatibilidade.

Resultado

Protocol-first design faz do contrato o centro da arquitetura: alinhamento de comportamento, fixação de circuitos, automação de geração e testes, evolução aditiva. O resultado é integração previsível, alta velocidade de desenvolvimento e resistência dos sistemas às mudanças de escala e de comando.