O header Sunset da API, e quando enviar um
6 min de leitura
Sunset é um único header de resposta, definido na RFC 8594,
que diz a um chamador quando um recurso vai parar de responder. Depreciação de API
cobre o cronograma completo de anunciar-lembrar-brownout-aposentar e os avisos que o acompanham;
isto é sobre o único sinal legível por máquina nesse cronograma, o que ele realmente diz, e o único
caso em que a própria RFC diz para não enviá-lo.
O que o header Sunset diz, e o que ele não diz?
Ele carrega uma única HTTP-date, o ponto em que se espera que o recurso pare de responder:
Sunset: Sat, 31 Dec 2028 23:59:59 GMTA RFC o chama de uma dica, não uma garantia: ela não promete que o recurso vai continuar funcionando até esse timestamp, e não diz nada sobre como vai ser a falha depois. O chamador pode receber um 4xx, um redirecionamento, ou nenhuma resposta; o header não diferencia. Um timestamp já no passado significa “agora, ou a qualquer momento”, não um erro no valor. Nada disso é imposto pelo protocolo. Um cliente que nunca lê o header se comporta exatamente como sempre se comportou, e descobre que o recurso sumiu do mesmo jeito que descobriria de qualquer forma.
Quando vale a pena realmente enviá-lo?
Só quando o recurso realmente vai parar de responder, não enquanto ele é apenas a opção não mais recomendada. A RFC é explícita: a depreciação acontece em dois estágios, e o campo Sunset pertence só ao segundo. A API continua totalmente operacional durante o primeiro estágio, o anúncio de que uma versão não é mais a preferida, e o campo não se aplica ali. Ele se aplica quando a versão está realmente programada para parar de responder.
Isso mapeia direto para o cronograma de depreciação: o header Deprecation sai desde o primeiro
dia, na etapa de anúncio; Sunset descreve a data em que o comportamento antigo realmente vai
parar, a mesma data que o cronograma de quatro etapas chama de
aposentadoria. Enviar Sunset no primeiro dia não é errado, já que a data já está fixada nesse
ponto, mas enviá-lo sem ter anunciado uma depreciação, ou fixá-lo para uma versão que vocês ainda
não se comprometeram a aposentar, diz aos chamadores algo que vocês ainda não decidiram.
Ele interage com cache?
Não, e a RFC diz isso diretamente: Sunset e o cache HTTP resolvem problemas não relacionados e
devem ser lidos como complementares, não sobrepostos. Os headers de cache dizem quando uma cópia em
cache é segura para reutilizar; Sunset não diz nada sobre o estado atual do recurso, só que o
recurso em si vai deixar de existir. Uma resposta pode ser totalmente cacheável até o exato momento
em que ela expira pelo sunset. Não usem um para aproximar o outro, e não assumam que um max-age
longo anula uma data de sunset se aproximando, nem o contrário.
Um único header pode encerrar mais de um endpoint?
O header se aplica ao recurso que o retornou, mas a RFC permite que um serviço documente um escopo mais amplo: uma data de Sunset no recurso raiz de uma API pode ser definida para significar que a API inteira vai sair do ar, não só aquela URL. A pegadinha é que isso só funciona para chamadores que já conhecem a regra de escopo de vocês. Um chamador lendo o header ao pé da letra vê um sunset no único recurso que pediu e nada mais, então um escopo mais amplo precisa estar escrito em algum lugar que o chamador consiga encontrar, não apenas implícito.
O que deveria acompanhar o header?
Um link para onde a aposentadoria é explicada. A RFC 8594 registra sua própria relação de link
sunset exatamente para isso: apontar para um recurso que descreve a política de aposentadoria, a
data que se aproxima, ou como migrar, separado do timestamp puro do header.
HTTP/1.1 200 OK
Sunset: Sat, 31 Dec 2028 23:59:59 GMT
Link: <https://example.com/docs/sunset-policy>; rel="sunset"Apontar esse link para os próprios exemplos de changelog de vocês, ou para
uma página de migração dedicada, transforma um header que quase nenhum código de cliente inspeciona
em algo que um humano que vai procurar encontra imediatamente. Combinem isso com a relação
successor-version vinda de os headers de depreciação
e o chamador recebe, só pela resposta, tanto para onde ir quanto o que substitui esta versão.
Como isso fica na prática, do início ao fim?
Digamos que v1 vai sair do ar em 1º de março de 2027. O anúncio de depreciação no primeiro dia
adiciona Deprecation e Link: rel="successor-version" a toda resposta v1, conforme os headers
de depreciação, mas segura o Sunset até que a data de aposentadoria
esteja realmente fixada, em vez de ser um placeholder. Uma vez que esteja, toda resposta v1
carrega:
HTTP/1.1 200 OK
Deprecation: @1756425600
Sunset: Mon, 01 Mar 2027 00:00:00 GMT
Link: <https://api.example.com/v2/reports>; rel="successor-version"
Link: <https://example.com/docs/sunset-policy>; rel="sunset"O gateway ou o monitoramento do chamador pode alertar em cada header de forma independente:
Deprecation diz que existe uma versão mais nova, Sunset diz que esta tem um prazo correndo.
Nenhum dos dois headers precisa mudar antes de 1º de março; o que muda é a própria resposta, no
dia, e durante qualquer janela de brownout agendada antes dele.
Um brownout muda o que o header diz?
O valor do header em si não precisa mudar por causa de um brownout agendado: a data de sunset
continua sendo a data de sunset, quer o recurso esteja falhando intermitentemente antes dela ou
não. O que muda é a resposta, não o header. Agendar janelas curtas de 410 Gone nas semanas antes
da data anunciada, como Depreciação de API descreve, é o que
transforma o primeiro contato do chamador com a falha em um ensaio, em vez do evento real no dia em
que a data do header chega.
FAQ
Algum cliente HTTP ou ferramenta real realmente lê o header Sunset? Raramente, do lado do cliente. O valor dele é sobretudo para quem opera a infraestrutura entre vocês e o chamador: um gateway de API ou uma ferramenta de monitoramento que vocês configuram para vigiar o header pode alertar a própria equipe de vocês, ou a de um parceiro, bem antes que o código do chamador chegue a notar. Tratem isso como um sinal ao redor do qual vocês constroem ferramentas, não um que já podem supor que o outro lado tem.
Sunset é a mesma coisa que Cache-Control: max-age?
Não. max-age é sobre por quanto tempo uma cópia em cache continua válida; Sunset é sobre quando
o recurso deixa de existir de vez. Uma resposta pode carregar um max-age curto e uma data de
Sunset anos à frente, ou o contrário, e nenhum dos dois headers limita o outro.
Posso enviar Sunset para um único campo que vai sumir, e não o endpoint inteiro?
Não, o header tem escopo no recurso, ou seja, na URL, não em um campo dentro do corpo da resposta.
Para um campo, um parâmetro ou um valor de enum que vai sumir enquanto o endpoint em si continua no
ar, usem o header Deprecation e uma entrada de changelog em vez disso; Depreciação de
API cobre exatamente como anunciar esse tipo de mudança.
E se a data de sunset precisar mudar? Atualizem o valor do header e digam isso na entrada de changelog que a anunciou originalmente; mudar uma data publicada em silêncio é como um chamador decide que nenhuma das datas de vocês é real. A RFC enquadra o valor como uma dica exatamente porque datas às vezes mudam, mas uma data movida sem explicação custa a próxima também.
As afirmações técnicas deste artigo não foram revisadas de forma independente. Se algo estiver errado, avise a gente e vamos corrigir.