Public API'mde bir endpoint'i kullanımdan kaldırırken sunset sürecini nasıl yönetmeliyim?

Kısa cevap: Para ödeyen partner’ların kullandığı bir endpoint’i asla sessizce silmeyin.

Kısa cevap

Duyurulmuş, tarihli ve ölçülen bir sunset yürütün — iletişim kurun, response içinde sinyal verin, kullanımı sıfıra izleyin, sonra kaldırın. Buradaki temel hata, kaldırmayı bir mühendislik olayı gibi görmektir; oysa bu asıl olarak bir iletişim sürecidir ve route’u nihayet silen kod değişikliği, tüm işin en son ve en küçük adımıdır. Bu kararın bir üst katmanını, yani endpoint yerine sürümü emekliye ayırmayı API’de sürümleme kararları yazısında tartışmıştım.

Neden

1. Tarih yoksa aciliyet yoktur. Aciliyet yoksa kimse göç etmez; partner’a somut bir replacement ve gerçekçi bir pencere vermeden yapılan “yakında kaldıracağız” duyurusu hiçbir davranışı değiştirmez.
2. Duyuruyu insanlar okumaz, makineler okur. E-posta ve changelog tek başına yetmez; sinyal yanıtın içine girmezse entegrasyonun kendisi kaldırmadan haberdar olmaz.
3. Göremediğiniz şeyi emekli edemezsiniz. Kimin hangi sıklıkta çağırdığını bilmeden verilen bir kesme tarihi kumardır; ölçüm olmadan “kullanım sıfıra yaklaştı” cümlesini kuramazsınız.
4. Sözleşme gerçekliği takvimden önce gelir. Göçün ortasındaki büyük bir ödeyen partner’ın production’ını kırmak, düzenli bir deprecation takvimine uymaktan çok daha pahalıya patlar.

Ne yapmalı

1. Kesin bir tarih ve göç yolu ile duyurun. E-posta + changelog + dokümantasyon; partner’a somut bir replacement ve gerçekçi bir pencere verin (ödeyen B2B için haftalar/aylar, günler değil).

2. Response’un kendisinde sinyal verin. İki ayrı başlık ve iki ayrı RFC var: Sunset (RFC 8594) kaynağın ne zaman yanıt vermez hâle geleceğini, Deprecation (RFC 9745) ne zaman kullanımdan kaldırıldığını söyler. Üçüncü olarak göç dokümanına bir Link başlığı ekleyin. Üçünü de ölmeye mahkûm endpoint’in her yanıtına koyun; böylece e-postayı görmezden gelen insanlar değil, makineler ve loglar da görür.

   Dikkat: Deprecation bir boolean değil — RFC 9745 değerin bir Date olmasını şart koşuyor (structured field; @ ile başlayan Unix zaman damgası).

   HTTP/1.1 200 OK
   Deprecation: @1780272000
   Sunset: Sat, 31 Oct 2026 23:59:59 GMT
   Link: <https://api.example.com/docs/migrate-v2>; rel="deprecation"; type="text/html"

3. Tüketici bazında kullanımı ölçün. Çağrıları API key/partner bazında loglayın; kimin hâlâ çağırdığını ve ne sıklıkta olduğunu tam olarak bilmeli ve o partner’lara doğrudan ulaşmalısınız.

4. Kesmeden önce brownout yapın. Tarihe yaklaşırken kısa, planlı kesintiler uygulayın (birkaç dakika 410/503 dönün, süreyi kademeli artırın). Bu, her başlığı ve e-postayı görmezden gelen entegrasyonları etki hâlâ geri alınabilirken yüzeye çıkarır.

5. Kaldırırken doğru statüyü dönün. Sessiz bir 500 değil; replacement’ı açıklayan bir gövdeyle 410 Gone (veya 404) dönün. Bu açıklayıcı yanıtı, kaldırmadan sonra uzun süre ayakta tutun.

6. Bir eskalasyon valfi tutun. Göçün ortasındaki büyük bir ödeyen partner için geçici bir allowlist/uzatma, onların production’ını kırmaktan iyidir.

Sonuç: Ben olsam önce partner bazında kullanımı enstrümante ederdim, sonra her yanıta başlıkları koyarak tarihli bir sunset yayınlar, tarihe yakın birkaç brownout yapar ve ancak kullanım sıfıra yaklaşınca keserdim — üstelik notu her seferinde kaçıran o tek partner için elle bir uzatma valfi bırakarak. Public API’de itibar, tek bir sessiz kaldırmayla kaybedilir.