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

> Kullanımı partner bazında ölçün, her yanıta Sunset ve Deprecation başlığı koyun, tarihli sunset duyurup brownout yapın, kullanım sıfıra yaklaşınca kesin.

- Soruldu: 2026-07-11
- Yanıtlandı: 2026-07-17
- Soran: Burak
- Etiketler: api, api-design
- Kaynak: https://muhammetsafak.com/tr/sor-bakalim/public-apimde-bir-endpointi-kullanimdan-kaldirirken-sunset-surecini-nasil-yonetmeliyim/
- Dil: tr-TR
- Yazar: Muhammet Şafak

---
**Soru:** Public bir API işletiyorum ve üç eski endpoint'i kaldırmak için işaretledim. Ama birkaç para ödeyen partner bu endpoint'lere hâlâ her gün istek atıyor.

Bu endpoint'leri partner'ların entegrasyonunu kırmadan nasıl emekliye ayırırım? Sunset sürecini adım adım nasıl yönetmeliyim, hangi sinyalleri vermeliyim ve gerçekten ne zaman kesmeliyim?


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](/tr/blog/api-tasariminda-surumleme-versioning-kararlari/) 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
   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.

## İlgili Yazılar

- [API tasarımında sürümleme (versioning) kararları](/tr/blog/api-tasariminda-surumleme-versioning-kararlari/) — Blog
- [API hata gövdelerimi RFC 7807 problem+json biçimine mi taşımalıyım?](https://muhammetsafak.com/tr/sor-bakalim/api-hata-govdelerimi-rfc-7807-problem-json-tasimaliyim/) — Sor Bakalım
- [OpenAPI şemasını önce mi yazmalıyım yoksa koddan mı üretmeliyim?](https://muhammetsafak.com/tr/sor-bakalim/openapi-semasini-once-mi-yazmaliyim-yoksa-koddan-mi-uretmeliyim/) — Sor Bakalım
- [Ödeme webhook'u aynı bildirimi tekrar gönderiyor; idempotency'i nasıl kurarım?](https://muhammetsafak.com/tr/sor-bakalim/webhook-mukerrer-bildirim-idempotency-ve-hmac/) — Sor Bakalım