Resumo

  • A RFC 9745, publicada em março de 2025, definiu Deprecation com uma data no formato Structured Fields. O recurso pode manter seu comportamento mesmo depois da data.
  • Um Link com relação deprecation aponta para política ou instruções de migração e pode surgir antes do cabeçalho datado. A RFC 8594, de 2019, reservou Sunset para o momento em que se espera que o recurso deixe de responder.
  • O aviso se aplica inicialmente ao recurso da resposta. O provedor precisa explicar qualquer alcance maior; respostas datadas de serviços concretos mostrariam onde o campo foi usado.

O sucesso que trouxe uma advertência

Uma API pode se aproximar do fim sem falhar uma única verificação de disponibilidade. Ela entrega o conteúdo normal enquanto seu operador prepara um substituto e desencoraja novas integrações. Se essa decisão fica apenas numa página de documentação, a equipe que observa as respostas pode não encontrá-la. Se só aparece quando o serviço cai, a janela para testar e lançar um cliente novo já se fechou.

A RFC 9745 pôs o anúncio na própria resposta HTTP. Deprecation traz a data de depreciação do recurso identificado naquela resposta. O valor usa o Date de Structured Fields. O exemplo Deprecation: @1688169599 indica 30 de junho de 2023 às 23h59min59s UTC. Uma data futura marca quando a condição começará; uma data passada diz que já começou. O recurso pode continuar entregando respostas nos dois casos.

Esse contraste faz o campo interessante. O mesmo pacote confirma que a operação de hoje funcionou e avisa que a dependência precisa de outro futuro. A especificação diz que deprecar não altera o comportamento do recurso. Para a equipe cliente, porém, cada nova integração passa a acumular um trabalho de saída. Disponibilidade corrente e bom investimento técnico deixaram de ser a mesma pergunta.

O alcance do aviso também tem limite definido. O campo diz respeito ao recurso daquela resposta. Se o operador pretende descontinuar uma API inteira ou vários caminhos, deve publicar como a data de um recurso se aplica aos demais. Uma captura isolada prova a existência do aviso naquele contexto; a fronteira mais ampla vem das regras do provedor.

A política pode aparecer primeiro

A RFC 9745 também registrou a relação deprecation para Link. O servidor pode apontar para um documento com política, alternativas e guia de migração. Esse elo pode ser enviado antes da data de depreciação. Nesse momento, o cliente já consegue descobrir como o provedor planeja avisar sobre o ciclo de vida, enquanto o recurso ainda não entrou no estado deprecado.

Uma data sozinha não adapta credenciais, formatos de resposta ou bancos de dados. O documento vinculado precisa dar um caminho que uma equipe consiga executar. O vínculo o torna encontrável a partir da interface em operação. O provedor escolhe o conteúdo e o momento da publicação; o usuário da API precisa reservar engenheiros, testes e uma janela de lançamento. A padronização do sinal torna a decisão visível, mas não divide igualmente o custo.

Depreciação e Sunset marcam fases diferentes

A RFC 8594 havia definido Sunset em maio de 2019 para anunciar quando uma URI deverá deixar de responder. Seu valor usa uma data HTTP. Deprecation anuncia quando o recurso deixa de ser uma boa base para dependências novas, mesmo que continue operacional. Um campo fala da escolha de continuar construindo; o outro, da futura disponibilidade esperada.

O texto de 2025 permite os dois campos e exige que Sunset não venha antes de Deprecation. Seu exemplo coloca a depreciação em 30 de junho de 2023 e o fim esperado um ano depois. Trocar a ordem produziria uma agenda absurda: fechar antes de avisar que o recurso perdeu a recomendação. A sintaxe preserva outra distinção histórica: Deprecation usa a data estruturada com @; Sunset, a data HTTP tradicional.

Os campos comunicam o calendário do operador aos clientes. Sua utilidade depende de escopo claro, substituto praticável e ações compatíveis com o aviso. Para medir adoção real faltam respostas datadas de serviços identificados. A norma já registra uma mudança importante: uma interface que funciona ganhou meios de dizer, na própria resposta, que o futuro deve ser construído em outro lugar.