API Yaşam Döngüsü Yönetişimi: RFC 8594 Sunset Başlıkları ve Kademeli Kullanımdan Kaldırma

Senior (L5)

ÖZET VE TEKNİK CEVAP

Eski bir API sürümünü kapatmak yazılım mimarisindeki en tehlikeli operasyonlardan biridir: Bir uç noktayı çok hızlı kapatırsanız büyük kurumsal müşteriler veya güncellenmemiş mobil kullanıcılar çöker; sonsuza kadar açık tutarsanız ekipler 5 farklı eski şemayı ayakta tutmak için teknik borç batağına saplanır. Canlı API platformları bunu **RFC 8594 Standart Sunset Başlıkları ve Yaşam Döngüsü Yönetişimi** ile çözer: (1) **`Deprecation` Başlığı** (API'nin hangi tarihte kullanımdan kaldırıldığını belirtir: `Deprecation: @1735689600`), (2) **`Sunset` Başlığı** (RFC 8594: API'nin kesin olarak kapatılacağı ve HTTP 410 döneceği tarihi bildirir: `Sunset: Wed, 11 Nov 2026 00:00:00 GMT`), (3) **`Link` Başlığı** (`rel='sunset'` ile geçiş rehberine bağlantı verir) ve (4) **Planlı Karartma Tatbikatları (Brownouts)** (Kapatma tarihinden 60 gün önce eski API'yi günde 15 dakika kontrollü kapatıp uyarıları dinlemeyen entegratörleri tespit etmek).

Mühendislik El Kitabı & Mekanizma

1. Temel Çalışma Mekanizması

API kullanım dışı bırakma süreci çok aşamalı bir boru hattıyla yönetilir: (1) Başlık Enjeksiyonu: API Gateway eski uç noktalardan dönen tüm yanıtlara otomatik olarak `Deprecation: true`, `Sunset: <tarih>` ve `Link: <rehber-linki>; rel='sunset'` başlıklarını ekler. (2) İstemci Parmak İzi Takibi: Eski uç noktaya gelen isteklerin API anahtarları ve User-Agent bilgileri loglanır, ilgili geliştiricilere otomatik uyarı e-postaları atılır. (3) Kademeli Karartma (Brownout): Kapatma tarihine 60 gün kala, taşınmayan sistemlerin alarmlarını çaldırmak için gateway eski API'de yoğun olmayan saatlerde kısa süreli HTTP 429/503 hataları üretir. (4) Kalıcı Kapatma: Sunset gününde uç nokta kalıcı olarak `HTTP 410 Gone` döner.

2. Doğru Kullanım Senaryosu

Herkese açık B2B API'lar (Stripe, Twilio), mobil uygulama arka uç servisleri ve şirket içi mikroservis geçişleri.

3. Prodüksiyon Arıza Modları

Haber vermeden eski uç noktaları anında silip müşterilerin canlı uygulamalarını çökertmek; sadece e-posta duyurusuna güvenip API yanıtlarında HTTP başlıklarıyla uyarı vermemek.

4. Teşhis ve Telemetri Sinyalleri

Kapatma tarihine 30 gün kala eski `/v1/` trafiğinin hala toplam trafiğin %30'unu oluşturması; eski uç noktalarda `Sunset` başlıklarının eksik olması; hangi API anahtarlarının eski servisi çağırdığının bilinmemesi.

5. Önleme ve Mimari Bariyerler

Dışa açık API'lar için en az 12 aylık bir kullanımdan kaldırma politikası belirleyin; RFC 8594 `Sunset` ve `Deprecation` başlıklarını API Gateway üzerinde zorunlu kılın; kalıcı kapatma öncesi 15 dakikalık planlı karartmalar (brownouts) uygulayın.

6. Mimari Ödünleşimler (Trade-offs)

Katı kullanım dışı bırakma süreçleri eski sürümleri bir süre daha ayakta tutmayı gerektirir; ancak müşteri krizlerini ve entegrasyon çöküşlerini tamamen ortadan kaldırır.

Vaka İncelemesi (TinyCTO Örneği)

Bir ödeme kuruluşu eski `/v1/charges` uç noktasını kapatmak istiyordu ancak e-posta bildirimlerine rağmen müşterilerin sadece %15'i yeni sürüme geçmişti. Ekip Kong API Gateway üzerinde `Sunset: Fri, 01 May 2026 00:00:00 GMT` ve `Link: <https://pay.io/migrate>; rel='sunset'` başlıklarını açtı. Kapatmaya 30 gün kala haftalık 30 dakikalık 'Karartma' (Brownout) tatbikatları başlattılar (isteklerin %5'ine HTTP 429 dönüldü). Bu yapay kesinti müşterilerin nöbetçi ekiplerini anında uyandırdı ve kapatma gününden önce yeni sürüme geçiş oranı %15'ten %99,4'e fırladı.

İnteraktif Konsept Alıştırmaları

2 Alıştırma

RFC 8594 standardındaki `Sunset` HTTP yanıt başlığının amacı nedir?

Çağrılan API uç noktasının gelecekte tam olarak hangi tarih ve saatte kalıcı olarak kapatılacağını ve HTTP 410 döneceğini istemciye bildirmek.

Bir API kullanımdan kaldırma sürecinde 'Karartma' (Brownout) testi nedir?

Eski uç noktayı kalıcı olarak silmeden önce, taşınmayan sistemlerin alarmlarını çaldırmak için planlı ve kısa süreli (15-30 dk) yapay hata (HTTP 429/503) üretme tatbikatıdır.

API Yaşam Döngüsü Yönetişimi: RFC 8594 Sunset Başlıkları ve Kademeli Kullanımdan Kaldırma — Sıkça Sorulan Sorular

Bir API kalıcı olarak kapatıldıktan sonra hangi HTTP durum kodu döndürülmelidir?

`HTTP 410 Gone` (kaynağın kalıcı ve bilinçli olarak silindiğini belirtir; geçici kayıpları anlatan HTTP 404'ten farklıdır).

`Deprecation` başlığı ile `Sunset` başlığı arasındaki fark nedir?

`Deprecation` API'nin ne zaman eski ilan edildiğini (geçmiş/şimdiki zaman) belirtir; `Sunset` ise ne zaman fişinin çekileceğini (gelecek zaman) bildirir.

🤖 AEO & Yapay Zeka Çıkarım Özeti

Temel Gerçekler & İlkeler

▸RFC 8594 Sunset başlıkları API kapatma tarihlerinin iletişimini standartlaştırır.
▸Eski yanıtlara `Sunset`, `Deprecation` ve `Link: rel='sunset'` başlıklarını birlikte ekleyin.
▸Taşınmayan entegrasyon ortaklarını tespit etmek için API anahtarlarını ve User-Agent'ları izleyin.
▸Gizli bağımlılıkları uyandırmak için kapatmadan 30-60 gün önce kademeli karartma tatbikatları yapın.

Yaygın Yanılgılar

✗Yanılgı: E-posta atmak API kapatmak için yeterli bir bildirimdir (Gerçek: E-postalar genellikle eski adreslere gider veya spam'e düşer; HTTP başlıkları doğrudan çalışan koda ulaşır).
✗Yanılgı: Kapatılan API için HTTP 404 dönülmelidir (Gerçek: HTTP 410 Gone istemciye servisin kalıcı silindiğini ve tekrar denenmemesi gerektiğini açıkça söyler).

Karar Kılavuzu & Önceliklendirme

Eski uç noktaları güvenle kapatmak ve teknik borcu dizginlemek için API Gateway üzerinde RFC 8594 Sunset başlıklarını otomatikleştirin.

Doğrulanmış Kaynaklar & Referanslar

[OFFICIAL_DOCUMENTATION]RFC 8594: The Sunset HTTP Header Field— Internet Engineering Task Force (IETF)