Versionamento de API: estratégia simples e previsível

Versionamento de API: estratégia simples e previsível — Boas práticas são atalhos para o futuro: menos retrabalho, menos regressão, mais clareza.

O objetivo aqui é prático: decisões pequenas que melhoram confiabilidade e manutenção. Se você já lidou com bugs intermitentes, sabe o valor de padrões simples.

Como eu abordo

• Comece com o caso real (o que está quebrando ou ficando caro).
• Defina uma regra pequena e aplicável (sem reescrever tudo).
• Instrumente: teste, log ou métrica para confirmar melhora.
• Documente o “porquê” em poucas linhas para não perder contexto.

Armadilhas comuns

• Otimizar cedo sem medir.
• Misturar camadas (controller fazendo SQL, por exemplo).
• Não registrar contexto (request id, rota, usuário) nos logs.
• Apostar em “mágica” de framework sem entender o fluxo.

Checklist rápido

• Qual é o risco principal (segurança, performance, disponibilidade)?
• Como eu valido a mudança (teste, log, métrica)?
• O que pode dar errado e como reverter?
• Quem mantém isso daqui a 3 meses?

Trecho de código

<?php
declare(strict_types=1);

final class JsonResponse
{
    public static function ok(array $data, int $status = 200): void
    {
        http_response_code($status);
        header('Content-Type: application/json; charset=utf-8');
        echo json_encode(['ok' => true, 'data' => $data], JSON_UNESCAPED_UNICODE);
    }
}

Se esta nota te poupou tempo, anote o que você ajustou e por quê. Isso vira um guia interno com o tempo.