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. 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.

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). Tarih yoksa aciliyet yoktur; aciliyet yoksa kimse göç etmez.
2. Response’un kendisinde sinyal verin. RFC 8594 Sunset başlığı + Deprecation başlığı + göç dokümanına bir Link başlığını, ölmeye mahkûm endpoint’in her yanıtına ekleyin. Böylece e-postayı görmezden gelen insanlar değil, makineler ve loglar da görür.
3. Tüketici bazında kullanımı ölçün. Göremediğiniz şeyi emekli edemezsiniz. Ç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. Sözleşme/SLA gerçekliği, düzenli bir deprecation takviminden önce gelir.

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

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.