Uma API não é compatível apenas porque mantém a mesma rota ou versão. Seus consumidores também dependem da estrutura dos dados, das regras de validação, dos valores padrão e do comportamento diante de erros. Se diferentes clientes são atualizados em ritmos distintos, uma mudança que parece pequena para quem mantém o servidor pode interromper um aplicativo móvel, uma integração de terceiros ou um processo interno.
Uma política de compatibilidade de dados em APIs PHP transforma esse risco em decisões explícitas: quais mudanças são aceitas, como são implantadas e quais testes devem ser aprovados antes de descontinuar um contrato. Não existe uma regra universal que torne qualquer mudança compatível; é preciso considerar como cada consumidor lê e envia os dados.
O contrato inclui dados, validação e comportamento
O contrato de uma API abrange mais do que o esquema documentado. Inclui os campos e seus tipos, se podem ser omitidos ou ser nulos, como datas e valores monetários são interpretados, quais valores uma solicitação aceita, o formato dos erros e as garantias sobre a resposta. Também inclui regras observáveis, como a ordem de uma coleção quando os clientes dependem dela ou a estabilidade de um identificador.
No PHP, objetos de transferência, validadores e serializadores costumam materializar partes desse contrato. Revisar apenas o controlador pode deixar mudanças incompatíveis ocultas em uma regra de validação, em um recurso de resposta ou em um mapeamento entre o modelo e a API. É recomendável documentar o contrato com base no que o cliente realmente observa, e não na estrutura interna das classes ou tabelas.
Classificar mudanças de acordo com o consumidor
A classificação é uma ferramenta de avaliação, não uma garantia automática. Uma mudança aditiva geralmente mantém o funcionamento de clientes que ignoram campos desconhecidos, mas pode quebrar consumidores que convertem a resposta para uma estrutura rígida ou validam os dados com base em um esquema fechado. Da mesma forma, um novo campo opcional em uma solicitação pode ser inofensivo para clientes antigos, enquanto torná-lo obrigatório não é.
- Normalmente aditivas: adicionar um campo opcional a uma solicitação ou resposta, ou adicionar um valor a uma coleção, desde que os consumidores tolerem esses elementos.
- Potencialmente incompatíveis: remover ou renomear um campo, alterar seu tipo, tornar obrigatório um campo opcional, mudar o formato de um erro ou modificar o significado de um valor existente.
- Dependentes do contexto: alterar a ordem, a precisão numérica, o fuso horário, a semântica de um estado ou os critérios de paginação. Mesmo que o esquema não mude, o resultado pode mudar para o cliente.
Antes de aprovar uma mudança, identifique os consumidores e verifique como processam os dados. Um campo desconhecido pode ser ignorado, provocar um erro de validação ou ser exposto a uma lógica que não o esperava. Não presuma que todas as linguagens, bibliotecas ou versões de clientes reagem da mesma forma.
Fazer evoluir solicitações e respostas com cautela
Nas respostas, adicionar um campo é mais seguro se for considerada a possibilidade de clientes rígidos rejeitarem propriedades adicionais. Se um campo mudar de significado ou de tipo, não o reutilize silenciosamente. Introduza um novo campo com semântica clara, documente sua relação com o anterior e mantenha ambos durante uma transição definida.
Nas solicitações, distinguir entre ausente, nulo e vazio é essencial. No PHP, uma validação que trata a ausência de uma chave da mesma forma que seu valor null pode apagar dados ou aplicar valores padrão inesperados. Defina o significado de cada caso e teste clientes novos e antigos. Para um campo novo, considere aceitar inicialmente sua ausência e atribuir um comportamento compatível, em vez de exigi-lo desde a primeira implantação.
Versionar rotas não é a única opção. É possível fazer um contrato evoluir mantendo a rota se as mudanças forem compatíveis, ou publicar uma nova versão quando não forem e a coexistência fizer sentido operacional. Em ambos os casos, documente a política de suporte: uma etiqueta de versão, por si só, não informa por quanto tempo um contrato continuará disponível.
Implantar o banco de dados e a API em etapas
Uma implantação segura separa as mudanças de armazenamento da exposição do novo comportamento. Uma sequência comum é ampliar o esquema, implantar código capaz de operar com a estrutura antiga e a nova, migrar os dados se necessário e, por fim, ativar a nova leitura ou escrita. A remoção de colunas ou fluxos antigos vem depois, quando houver evidências suficientes de que deixaram de ser necessários.
Essa abordagem de expansão e contração evita que uma versão do aplicativo espere por uma coluna que ainda não existe ou que uma nova implantação deixe de funcionar com processos antigos. Em sistemas com várias instâncias ou workers em segundo plano, considere que diferentes versões do código podem coexistir durante a implantação. As migrações devem ser compatíveis com essa coexistência e contar com uma estratégia de recuperação caso uma etapa falhe.
A exposição gradual — por exemplo, habilitar um recurso para uma parte controlada dos consumidores — pode limitar o impacto, mas não equivale a uma divulgação pública nem substitui a compatibilidade. Use controles de ativação quando permitirem observar e reverter o comportamento; defina previamente quais condições interrompem a expansão.
Medir o uso sem registrar dados sensíveis
Para saber quais consumidores continuam usando um contrato, a telemetria deve identificar a versão ou o recurso relevante sem armazenar corpos de solicitações ou respostas que contenham informações pessoais, credenciais ou dados comerciais. Registre sinais mínimos, como rota, versão declarada do cliente, resultado e data; limite o acesso e a retenção de acordo com as necessidades operacionais e as obrigações aplicáveis.
O sinal deve ser útil para a tomada de decisões. Diferencie solicitações de usuários reais de testes, novas tentativas ou tráfego automatizado; observe também erros, latência e mudanças no volume. Se não houver um identificador de cliente confiável, não deduza sua identidade a partir de dados sensíveis. Reconheça que proxies, chaves compartilhadas e clientes que não enviam a versão podem deixar pontos cegos.
Descontinuar um contrato com critérios verificáveis
Não descontinue uma versão apenas porque passou o prazo anunciado. Defina sinais e limites de acordo com o risco: ausência sustentada de tráfego identificável, migração confirmada de integrações conhecidas, estabilidade da versão sucessora e um procedimento de suporte para exceções. Se persistir tráfego desconhecido, investigue antes de interpretar a falta de identificação como falta de uso.
Comunique com antecedência o que muda, quem será afetado, qual é a alternativa, as datas previstas e como testar a migração. Mantenha as informações em uma documentação acessível às equipes consumidoras e estabeleça um canal para relatar incompatibilidades. Se o impacto não puder ser revertido rapidamente, considere uma transição mais longa ou a coexistência temporária dos contratos.
Lista de verificação antes da publicação
- Os campos, tipos, nulabilidade, valores padrão e erros afetados foram documentados?
- O comportamento de clientes tolerantes e rígidos diante de campos novos ou ausentes foi verificado?
- Os testes de contrato abrangem consumidores conhecidos e casos-limite de validação?
- A migração do banco de dados permite a coexistência com versões anteriores do aplicativo?
- Há métricas suficientes para detectar erros e o uso do contrato sem capturar dados sensíveis?
- Foram definidos responsáveis, comunicação, critérios de reversão e condições para remover o que é antigo?
Uma política útil não promete que nenhuma mudança quebrará nenhum cliente. Ela explicita as premissas, limita as surpresas e permite agir com base em evidências. Revise essas decisões a cada mudança de contrato, especialmente quando a API tiver consumidores externos cujo ciclo de atualização não é controlado pela equipe.
