El header sunset de una API, y cuándo enviarlo
6 min de lectura
Sunset es un único header de respuesta, definido en RFC 8594,
que le dice a un llamante cuándo un recurso dejará de responder. Deprecación de
API cubre el calendario completo de anunciar-recordar-degradar-retirar
y los avisos que lo acompañan; esto trata de la única señal legible por máquina en ese calendario,
qué dice en realidad, y el único caso en que la propia RFC dice que no hay que enviarla.
¿Qué dice el header Sunset, y qué no dice?
Lleva una única fecha HTTP, el punto en el que se espera que el recurso deje de responder:
Sunset: Sat, 31 Dec 2028 23:59:59 GMTLa RFC lo llama una pista, no una garantía: no promete que el recurso seguirá funcionando hasta ese momento exacto, y no dice nada sobre cómo se verá el fallo después. Los llamantes pueden recibir un 4xx, una redirección, o ninguna respuesta; el header no distingue. Una fecha ya pasada significa “ahora, o en cualquier momento” en vez de un error en el valor. Nada de esto lo hace cumplir el protocolo. Un cliente que nunca lee el header se comporta exactamente como siempre lo ha hecho, y descubre que el recurso desapareció de la misma forma en que lo habría descubierto de todos modos.
¿Cuándo deberías enviarlo en realidad?
Solo cuando el recurso vaya a dejar de responder de verdad, no mientras simplemente ya no es la opción recomendada. La RFC es explícita en que la deprecación ocurre en dos etapas, y el campo del header Sunset pertenece solo a la segunda: la API sigue completamente operativa durante la primera etapa, el anuncio de que una versión ya no es la preferida, y el campo no aplica ahí. Aplica en cuanto la versión de verdad tiene programado dejar de responder.
Eso encaja directamente con el calendario de deprecación: el header Deprecation sale desde el
primer día, en el paso del anuncio; Sunset describe la fecha en que el comportamiento antiguo de
verdad se detendrá, la misma fecha que el calendario de cuatro pasos
llama la retirada. Enviar Sunset el primer día no está mal, porque la fecha ya está fijada para
entonces, pero enviarlo sin haber anunciado también una deprecación, o fijarlo para una versión que
en realidad no te has comprometido a retirar, le dice a los llamantes algo que todavía no has
decidido.
¿Interactúa con el cacheo?
No, y la RFC lo dice directamente: Sunset y el cacheo HTTP resuelven problemas sin relación entre
sí y deben leerse como complementarios, no como superpuestos. Los headers de caché dicen cuándo es
seguro reutilizar una copia cacheada; Sunset no dice nada sobre el estado actual del recurso, solo
que el recurso en sí dejará de existir. Una respuesta puede ser totalmente cacheable hasta el mismo
momento en que se retira. No uses uno para aproximar el otro, ni asumas que un max-age largo
cancela una fecha de sunset cercana, ni al revés.
¿Puede un solo header retirar más de un endpoint?
El header aplica al recurso que lo devolvió, pero la RFC permite que un servicio documente un alcance más amplio: una fecha Sunset en el recurso raíz de una API puede definirse para significar que toda la API desaparece, no solo esa URL. La trampa es que esto solo funciona para llamantes que ya conocen tu regla de alcance. Un llamante que lee el header al pie de la letra ve un sunset en el único recurso que pidió y nada más, así que un alcance más amplio tiene que quedar escrito en algún sitio donde un llamante pueda encontrarlo, no dado por sentado.
¿Qué debería acompañar al header?
Un link a donde se explica la retirada. RFC 8594 registra su propia relación de link sunset
exactamente para esto: apuntar a un recurso que describe la política de retirada, la fecha próxima,
o cómo migrar, por separado de la fecha desnuda del header.
HTTP/1.1 200 OK
Sunset: Sat, 31 Dec 2028 23:59:59 GMT
Link: <https://example.com/docs/sunset-policy>; rel="sunset"Apuntar ese link a tus propios ejemplos de changelog o a una página de
migración dedicada convierte un header que casi ningún código cliente inspecciona en algo que una
persona que sí investiga encuentra de inmediato. Combínalo con la relación successor-version de
los headers de deprecación
y un llamante obtiene tanto a dónde ir como qué reemplaza a este, solo con la respuesta.
¿Cómo se ve esto de principio a fin?
Supón que v1 desaparece el 1 de marzo de 2027. El anuncio de deprecación del primer día añade
Deprecation y Link: rel="successor-version" a cada respuesta de v1, según los headers de
deprecación, pero espera con Sunset hasta que la fecha de retirada
esté fijada de verdad en vez de ser un marcador de posición. Una vez que lo está, cada respuesta de
v1 lleva:
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"El gateway o el monitoreo de un llamante puede alertar sobre cualquiera de los dos headers de forma
independiente: Deprecation dice que existe una versión más nueva, Sunset dice que esta tiene un
reloj corriendo. Ningún header necesita cambiar antes del 1 de marzo; lo que cambia es la respuesta
en sí, el día señalado, y durante cualquier ventana de brownout programada antes.
¿Un brownout cambia lo que dice el header?
El valor del header no necesita moverse por un brownout programado: la fecha de sunset sigue siendo
la fecha de sunset, falle o no el recurso de forma intermitente antes de ella. Lo que cambia es la
respuesta, no el header. Programar ventanas breves de 410 Gone en las semanas previas a la fecha
anunciada, como describe Deprecación de API, es lo que convierte el
primer contacto de un llamante con el fallo en un ensayo en vez de la cosa real el día en que llega
la fecha del header.
FAQ
¿Algún cliente HTTP o herramienta real lee de verdad el header Sunset? Raramente, del lado del cliente. Su valor está sobre todo en quien opera la infraestructura entre tú y el llamante: un gateway de API o una herramienta de monitoreo que configures para vigilar el header puede alertar a tu propio equipo, o al de una socia, mucho antes de que el código del llamante lo note siquiera. Trátalo como una señal alrededor de la cual construyes herramientas, no como una que puedas asumir que el otro lado ya tiene.
¿Es Sunset lo mismo que Cache-Control: max-age?
No. max-age trata de cuánto tiempo sigue siendo válida una copia cacheada; Sunset trata de
cuándo el recurso deja de existir del todo. Una respuesta puede llevar un max-age corto y una
fecha Sunset a años de distancia, o al revés, y ningún header limita al otro.
¿Puedo enviar Sunset para un solo campo que desaparece, no para todo el endpoint?
No, el header tiene alcance de recurso, es decir la URL, no un campo dentro de su cuerpo de
respuesta. Para un campo, un parámetro o un valor de enum que desaparece mientras el endpoint en sí
sigue en pie, usa el header Deprecation y una entrada de changelog en su lugar; Deprecación de
API cubre cómo anunciar exactamente ese tipo de cambio.
¿Qué pasa si la fecha de sunset necesita moverse? Actualiza el valor del header y dilo en la entrada de changelog que la anunció originalmente; cambiar una fecha publicada en silencio es cómo un llamante decide que ninguna de tus fechas es real. La RFC enmarca el valor como una pista precisamente porque las fechas a veces sí se mueven, pero una fecha movida sin explicación te cuesta también la siguiente.
Las afirmaciones técnicas de este artículo no se han revisado de forma independiente. Si algo está mal, avísanos y lo corregiremos.