# 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://www.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. 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ığını, `Deprecation` başlığını ve 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
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.

## İlgili Yazılar

- [API tasarımında sürümleme (versioning) kararları](/blog/api-tasariminda-surumleme-versioning-kararlari/) — Blog
- [OpenAPI şemasını önce mi yazmalıyım yoksa koddan mı üretmeliyim?](https://www.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://www.muhammetsafak.com.tr/sor-bakalim/webhook-mukerrer-bildirim-idempotency-ve-hmac/) — Sor Bakalım
- [Birbirine bağımlı birden fazla işi, ilk hata hepsini iptal edecek şekilde errgroup ile mi yürütmeliyim?](https://www.muhammetsafak.com.tr/sor-bakalim/birbirine-bagimli-birden-fazla-isi-ilk-hata-hepsini-iptal-edecek-sekilde/) — Sor Bakalım