API sunset header'ı: ne zaman gönderilir

Sunset, RFC 8594’te tanımlanan, bir çağırana bir kaynağın ne zaman yanıt vermeyi durduracağını söyleyen tek bir yanıt header’ıdır. API deprecation tam duyur-hatırlat-brownout-emekliye ayır zaman çizelgesini ve onunla birlikte giden bildirimleri ele alır; bu yazı o zaman çizelgesindeki tek bir makine tarafından okunabilir sinyal hakkındadır, gerçekte ne söylediği hakkındadır, ve RFC’nin kendisinin onu göndermemeyi söylediği tek durum hakkındadır.

Sunset header’ı ne söyler, ne söylemez?

Kaynağın yanıt vermemesinin beklendiği noktayı, tek bir HTTP-date olarak taşır:

Sunset: Sat, 31 Dec 2028 23:59:59 GMT

RFC ona bir garanti değil bir ipucu der: kaynağın tam olarak o zaman damgasına kadar çalışmaya devam edeceğini vaat etmez, ve sonrasında başarısızlığın nasıl görüneceği hakkında hiçbir şey söylemez. Çağıranlar bir 4xx, bir yönlendirme, veya hiç yanıt alamayabilir; header ayrım yapmaz. Geçmişte kalan bir zaman damgası, değerdeki bir hata yerine “şimdi, veya herhangi bir an” anlamına gelir. Bunların hiçbiri protokol tarafından zorunlu kılınmaz. Header’ı hiç okumayan bir client tam olarak her zamanki gibi davranır, ve kaynağın gittiğini, zaten öğrenecek olduğu şekilde öğrenir.

Gerçekte ne zaman gönderilmeli?

Sadece kaynak gerçekten yanıt vermeyi durduracaksa, sadece artık önerilen seçim olmaktan çıktığında değil. RFC, deprecation’ın iki aşamada gerçekleştiğini açıkça belirtir, ve Sunset header alanı sadece ikincisine aittir: API, bir sürümün artık tercih edilmediğinin duyurulduğu birinci aşama boyunca tamamen çalışır durumda kalır, ve header alanı orada geçerli değildir. Sürüm gerçekten yanıt vermemesi planlandığında geçerli olur.

Bu, deprecation zaman çizelgesine doğrudan denk gelir: Deprecation header’ı ilk günden, duyuru adımından itibaren gönderilir; Sunset, eski davranışın gerçekten duracağı tarihi tanımlar, ki bu dört adımlı zaman çizelgesinin emekliye ayırma dediği aynı tarihtir. Sunset’i ilk gün göndermek yanlış değildir, çünkü tarih o zamana kadar zaten sabitlenmiştir, ama bir deprecation duyurmadan onu göndermek, veya gerçekten emekliye ayırmaya karar vermediğiniz bir sürüm için ayarlamak, çağıranlara henüz karar vermediğiniz bir şeyi söylemektir.

Caching ile etkileşir mi?

Hayır, ve RFC bunu doğrudan söyler: Sunset ve HTTP caching ilgisiz sorunları çözer ve üst üste binen değil tamamlayıcı olarak okunmalıdır. Caching header’ları önbelleğe alınmış bir kopyanın ne zaman yeniden kullanılmasının güvenli olduğunu söyler; Sunset kaynağın şu anki durumu hakkında hiçbir şey söylemez, sadece kaynağın kendisinin var olmayı bırakacağını söyler. Bir yanıt, sunset olduğu ana kadar tamamen cache’lenebilir olabilir. Birini diğerinin yerine kullanmayın, ve uzun bir max-age’in yaklaşan bir sunset tarihini iptal ettiğini, ya da tersini, varsaymayın.

Tek bir header birden fazla endpoint’i sunset yapabilir mi?

Header, onu döndüren kaynağa uygulanır, ama RFC bir servisin daha geniş bir kapsamı belgelemesine izin verir: bir API’nin ana kaynağındaki bir Sunset tarihi, sadece o tek URL’nin değil, tüm API’nin gittiği anlamına gelecek şekilde tanımlanabilir. Sorun şu ki bu sadece kapsam kuralınızı zaten bilen çağıranlar için işe yarar. Header’ı yüzeysel okuyan bir çağıran, istediği tek kaynakta bir sunset görür, başka hiçbir şey görmez, bu yüzden daha geniş bir kapsam, ima edilmek yerine çağıranın bulabileceği bir yere yazılmalıdır.

Header’ın yanında ne gönderilmeli?

Emekliye ayırmanın açıklandığı yere bir link. RFC 8594, tam olarak bunun için kendi sunset link ilişkisini kaydeder: header’ın çıplak zaman damgasından ayrı olarak, emekliye ayırma politikasını, yaklaşan tarihi, veya nasıl göç edileceğini açıklayan bir kaynağa işaret etmek için.

HTTP/1.1 200 OK
Sunset: Sat, 31 Dec 2028 23:59:59 GMT
Link: <https://example.com/docs/sunset-policy>; rel="sunset"

O linki kendi changelog örneklerinize veya özel bir migrasyon sayfasına yönlendirmek, neredeyse hiçbir client kodunun incelemediği bir header’ı, gerçekten bakan bir insanın anında bulduğu bir şeye dönüştürür. Onu deprecation header’larından successor-version ilişkisiyle birleştirin, ve bir çağıran sadece yanıttan hem nereye gideceğini hem de bunun yerine neyin geçtiğini alır.

Bu uçtan uca nasıl görünür?

v1’in 1 Mart 2027’de gideceğini varsayalım. İlk gündeki deprecation duyurusu, deprecation header’larına göre her v1 yanıtına Deprecation ve Link: rel="successor-version" ekler, ama emekliye ayırma tarihi bir yer tutucu değil gerçekten sabitlenene kadar Sunset’i bekletir. Sabitlendiğinde, her v1 yanıtı şunu taşır:

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"

Bir çağıranın gateway’i veya izlemesi her iki header üzerinde de bağımsız olarak uyarı verebilir: Deprecation daha yeni bir sürümün var olduğunu söyler, Sunset bunun üzerinde bir saat olduğunu söyler. Hiçbir header 1 Mart’tan önce değişmek zorunda değildir; değişen şey, o gün ve önceden planlanmış herhangi bir brownout penceresi sırasında, yanıtın kendisidir.

Bir brownout header’ın söylediğini değiştirir mi?

Header değerinin kendisinin planlanmış bir brownout için değişmesine gerek yoktur: kaynak öncesinde aralıklı olarak başarısız olsa da olmasa da sunset tarihi hâlâ sunset tarihidir. Değişen şey header değil, yanıttır. API deprecation’ın tarif ettiği gibi, duyurulan tarihten önceki haftalarda kısa 410 Gone pencereleri planlamak, bir çağıranın başarısızlıkla ilk temasını, header’ın tarihi geldiği gün gerçek olan yerine bir prova haline getiren şeydir.

FAQ

Gerçek HTTP client’ları veya araçları Sunset header’ını gerçekten okur mu? Client tarafında nadiren. Değeri çoğunlukla sizinle çağıran arasındaki altyapıyı işleten kişi içindir: header’ı izlemek için yapılandırdığınız bir API gateway’i veya bir izleme aracı, çağıranın kodu hiç fark etmeden çok önce kendi ekibinizi, veya bir ortağınkini, uyarabilir. Bunu, karşı tarafın zaten sahip olduğunu varsayabileceğiniz bir şey değil, etrafında araç inşa ettiğiniz bir sinyal olarak ele alın.

Sunset, Cache-Control: max-age ile aynı şey mi? Hayır. max-age, önbelleğe alınmış bir kopyanın ne kadar süre geçerli kaldığıyla ilgilidir; Sunset, kaynağın ne zaman tamamen var olmayı bırakacağıyla ilgilidir. Bir yanıt kısa bir max-age ve yıllar sonrasına ait bir Sunset tarihi taşıyabilir, ya da tersi, ve hiçbir header diğerini kısıtlamaz.

Tüm endpoint için değil, giden tek bir alan için Sunset gönderebilir miyim? Hayır, header kaynağa, yani URL’ye kapsamlıdır, yanıt gövdesi içindeki bir alana değil. Endpoint’in kendisi ayakta kalırken giden bir alan, parametre veya enum değeri için bunun yerine Deprecation header’ını ve bir changelog girdisini kullanın; API deprecation tam olarak bu tür bir değişikliği duyurmayı ele alır.

Sunset tarihinin değişmesi gerekirse ne olur? Header değerini güncelleyin ve bunu ilk başta duyuran changelog girdisinde belirtin; yayımlanmış bir tarihi sessizce değiştirmek, bir çağıranın hiçbir tarihinizin gerçek olmadığına karar vermesine yol açan şeydir. RFC değeri tam olarak tarihlerin bazen değiştiği için bir ipucu olarak çerçeveler, ama açıklama olmadan değişen bir tarih bir sonrakine de mal olur.

Bu yazıdaki teknik iddialar bağımsız olarak kontrol edilmedi. Yanlış bir şey varsa bize söyle, düzeltelim.

changeloop'ta ilgili sayfalar: Geliştirici dokümantasyonu, Changelog örnekleri