Regra

Evitar quebrar pública API contratos.
Alterações para públicos API endpoints que poderia quebrar
existentes cliente pedidos são de rutura mudanças.
Pense de a API contrato como a promessa - mudando
a promessa depois de clientes dependem dele dela quebra o seu código.

Linguagens suportadas: PHP, Java, C#, Python, JavaScript, TypeScript

Introdução

APIs públicas são contratos entre seu serviço e seus consumidores. Uma vez que os clientes dependem do formato da requisição, estrutura da resposta ou comportamento de um endpoint, alterá-lo quebra o código deles. Alterações que quebram a compatibilidade forçam todos os clientes a atualizar simultaneamente, o que é frequentemente impossível quando você não controla os clientes. Aplicativos móveis não podem ser atualizados à força, integrações de terceiros precisam de tempo para migração, e sistemas legados podem nunca ser atualizados.

Por que isso importa

Interrupção e confiança do cliente: Mudanças disruptivas na API causam falhas imediatas em aplicações cliente em produção. Usuários experimentam erros, perda de dados ou interrupções completas do serviço. Isso prejudica a confiança entre provedores e consumidores de API e viola o contrato implícito de que APIs estáveis permanecem estáveis.

Custos de Coordenação: Coordenar mudanças disruptivas entre várias equipes de clientes é caro e lento. Cada equipe precisa de tempo para atualizar o código, testar as mudanças e implantar. Para APIs públicas com clientes desconhecidos (aplicativos móveis, integrações de terceiros), a coordenação é impossível.

Proliferação de versões: Alterações disruptivas mal gerenciadas levam à manutenção de múltiplas versões de API simultaneamente. Cada versão requer caminhos de código, testes, documentação e correções de bugs separados, multiplicando exponencialmente a carga de manutenção.

Exemplos de código

❌ Não-conforme:

// Version 1: Original API
app.get('/api/users/:id', async (req, res) => {
    const user = await db.users.findById(req.params.id);
    res.json({ id: user.id, name: user.name });
});

// Version 2: Breaking change - renamed field
app.get('/api/users/:id', async (req, res) => {
    const user = await db.users.findById(req.params.id);
    res.json({
        id: user.id,
        fullName: user.name  // Breaking: 'name' renamed to 'fullName'
    });
});

Por que está errado: Renomear 'name' para 'fullName' quebra todos os clientes existentes que esperam o campo 'name'. O código do cliente acessando response.name receberá 'undefined', causando erros. Essa mudança força todos os clientes a atualizar simultaneamente ou falhar.

✅ Compatível:

// Version 2: Additive change - keeps old field, adds new
app.get('/api/users/:id', async (req, res) => {
    const user = await db.users.findById(req.params.id);
    res.json({
        id: user.id,
        name: user.name,           // Keep for backward compatibility
        fullName: user.name        // Add new field (deprecated 'name')
    });
});

// Or use API versioning
app.get('/api/v2/users/:id', async (req, res) => {
    const user = await db.users.findById(req.params.id);
    res.json({ id: user.id, fullName: user.name });
});

Por que isso importa: Mantendo o antigo nome campo mantém compatibilidade retroativa enquanto adiciona Nome Completo para novos clientes. Alternativamente, criando um novo endpoint versionado (/api/v2/) permite alterações disruptivas sem afetar clientes existentes que ainda utilizam /api/v1/.

Conclusão

Evolua APIs através de mudanças aditivas: adicione novos campos, adicione novos endpoints, adicione parâmetros opcionais. Quando mudanças disruptivas forem inevitáveis, use o versionamento de API para executar versões antigas e novas simultaneamente. Deprecie campos antigos com cronogramas claros e guias de migração antes de removê-los.