O Que é um API Contract? A Promessa Entre Serviços
Um API contract é o formato e comportamento acordados de uma interface, os endpoints, campos, tipos e casos de erro, dos quais os callers dependem.
Quando um serviço ou cliente chama outro, ele depende de que a interface chamada se comporte de certa forma. Esse conjunto de expectativas é o API contract. Ele pode ser escrito formalmente como uma spec OpenAPI ou implícito pelo uso, mas de qualquer forma, quebrá-lo quebra os callers. Tratar o contrato como um artifact de primeira classe e testável é o que torna deploys independentes seguros.
O que o contrato cobre
Os formatos de request e response, nomes e tipos de campos, campos obrigatórios versus opcionais, status codes, formatos de erro e garantias de comportamento como idempotência. Qualquer coisa da qual um consumer dependa faz parte do contrato, esteja documentada ou não.
Explícito versus implícito
Um contrato explícito é uma spec machine-readable contra a qual você pode validar. Um contrato implícito é apenas aquilo de que os consumers acabam dependendo. Contratos explícitos podem ser aplicados no CI; os implícitos são quebrados por acidente porque nada os verifica.
Por que importa para deploys
- Consumers e providers podem fazer deploy de forma independente se o contrato se mantiver.
- Um breaking change no contrato pode quebrar callers que você não controla.
- Um contrato estável é o que torna um microservice de fato independente.
- Contratos permitem que times trabalhem em paralelo contra um acordo.
Contract testing no CI
Contract tests verificam que um provider ainda satisfaz o que seus consumers esperam, e que os consumers programam contra o contrato real. Rodando na pipeline, eles pegam um breaking change antes de ele ir para produção, em vez de em um incidente de produção de um consumer.
Detectando breaking changes
Com uma spec explícita, o CI pode fazer um diff do contrato proposto contra o atual e falhar o build em um breaking change, remover um campo, restringir um tipo, então a backward compatibility vira um gate automatizado, não um code review esperançoso.
Gates de contrato rápidos
Validação de contrato e testes de consumer rodam a cada mudança em uma API compartilhada. Runners rápidos (como o Latchkey) evitam que essas verificações constantes atrasem os times que dependem da interface.
Principais conclusões
- Um API contract é tudo aquilo de que um caller depende sobre uma interface.
- Contratos explícitos e machine-readable podem ser aplicados no CI; os implícitos não.
- Contract testing é o que permite a providers e consumers fazerem deploy de forma independente.