Recursos · 33
Evolua os contratos de API sem perder clientes.
Descreva as solicitações, respostas e erros; teste versões e torne os webhooks seguros para reprodução.
Atualizado · 2 min
O que este guia ajuda a alcançar
- Redigir o contrato
- Esclarecer erros
- Testar a compatibilidade
- Planejar a desativação
Verificação rápida
- Quais clientes usam cada operação?
- Os erros têm tipos estáveis e status coerentes?
- Um cliente antigo tolera a mudança?
- As novas tentativas podem duplicar uma ação?
- Como a desativação será anunciada e verificada?
Método passo a passo
- 1
Inventariar os consumidores
Listar operações, clientes, usos, versões e proprietários. Separar o uso observado das suposições antes de alterar um campo.
Entregável: mapa de dependências do contrato.
- 2
Descrever solicitações e respostas
Manter uma descrição OpenAPI com esquemas, exemplos realistas e respostas de sucesso e falha. Verificar em relação ao serviço em execução.
Entregável: contrato versionado e testes de conformidade.
- 3
Estabilizar erros.
Usar status HTTP de acordo com sua semântica e, quando útil, um tipo de problema documentado conforme a RFC 9457. Não expor segredos em detalhes.
Entregável: catálogo de erros testado.
- 4
Classificar a alteração.
Inspecionar campos, tipos, valores, comportamento, tempos limite e paginação obrigatórios. Testar clientes antigos com a nova versão usando casos representativos.
Entregável: matriz de compatibilidade e decisão de versão.
- 5
Tornar as notificações robustas.
Para webhooks, planejar autenticação, entrega não ordenada, duplicatas e novas tentativas. Tornar o processamento idempotente onde a repetição for possível.
Entregável: cenário de reprodução e confirmação.
- 6
Lançamento com um caminho de saída
Publicar notas de migração, período de coexistência e contatos. Medir o uso da versão antiga e desativá-la somente após verificar os consumidores afetados.
Entregável: plano de migração e evidências de desativação.
Indicadores de gestão
| Indicador | O que mede | Primeira ação |
|---|---|---|
| Contrato | Operações descritas e comportamento de serviço correspondente | Corrigir divergência |
| Compatibilidade | Clientes representativos testados antes da alteração | Adicionar casos ausentes |
| Erros | Tipos documentados sem dados sensíveis | Revisar mensagens e esquemas |
| Migração | Uso da versão antiga com um proprietário | Auxiliar os clientes restantes |
Erros comuns
- Assumir que apenas um número de versão preserva a compatibilidade
- Documentar apenas respostas 200
- Retornar um rastreamento interno ou segredo em caso de erro
- Assumir que os webhooks chegam uma única vez e em ordem
Perguntas frequentes
O OpenAPI substitui os testes?
Não. Compare a descrição com as respostas reais e as necessidades do consumidor.
Toda alteração exige uma nova versão?
Não. Decida com base no impacto no cliente e no comportamento contratual; alterações incompatíveis exigem um plano explícito.
Por que erros de digitação?
Eles oferecem aos clientes uma maneira estável de identificar problemas e escolher uma ação.
Referências oficiais
As referências apoiam o método. Adapte as verificações ao seu contexto; elas não são uma certificação. Os títulos das referências originais e os documentos de origem podem estar em outro idioma.
