Geliştiricileri kaybetmeden bir API nasıl deprecate edilir

Bir API’yi deprecate etmek, bir şeyin bugün hâlâ çalıştığını ve belirtilen bir tarihte çalışmayı durduracağını duyurmak, sonra o sözün her iki yarısını da tutmaktır. Çoğu deprecation ikinci yarıda başarısız olur: tarih sessizce kayar, veya gelir ve bildirimi hiç görmemiş çağıranlar bunu bir hatadan öğrenir. Bir deprecation, etkilenen her çağıran ya göç ettiğinde ya da bireysel olarak göç etmediği söylendiğinde tamamlanmıştır.

API deprecation nedir?

Deprecation, bir endpoint’in, alanın veya versiyonun gitmekte olduğunu duyurmakla onu gerçekten kaldırmak arasındaki dönemdir. Bu dönem boyunca eski davranış çalışmaya devam eder, dokümantasyon gittiğini söyler, ve her yanıt makine tarafından okunabilir bir uyarı taşır. Kaldırma, genellikle sunset olarak adlandırılan ayrı, daha sonraki olaydır. İkisi karıştırılır, ve bu karışıklık hasarın gerçekleştiği yerdir: “deprecated” “belki zaten gitmiştir” anlamına gelmeye başlar, ve çağıranlar her iki kelimeye de güvenmeyi bırakır.

Bir deprecation dönemi ne kadar sürmeli?

Bir çağıranın öğrenip işi yapmasına yetecek kadar uzun, bunu yazdığınız andan değil bildirimin ona ulaştığı andan itibaren ölçülerek. Doksan gün, genel bir web API’si için yaygın taban çizgisidir. On iki ay, son kullanıcıların yüklediği yazılıma gömülü herhangi bir şey için normaldir, çünkü düzeltme onların sürüm sürecinden de geçmelidir. Google’ın versiyonlama kılavuzu AIP-185, makul bir geçiş süresi ister ve beta işlevselliğini kaldırmadan önce bile 180 gün önerir, ve Kubernetes deprecation politikasını aylar yerine sürüm sayısı olarak belgeler, ki bu çağıranlarınız sürüme göre güncellediğinde doğru birimdir.

Bir dönem seçin, onu politika olarak yazın, ve değişiklik başına karar vermeyi bırakın. Yayımlanmış bir politika, her deprecation’ı bir müzakereden bir kuralın uygulanmasına dönüştürür.

Deprecation politikasını yazmak pencerenin başını kapsar; bir API sürümünü kapatmak dönem gerçekten bittiğinde ve sürüm çalışmayı bıraktığında sonunda gereken ayrı bildirimi kapsar.

Deprecation zaman çizelgesi

Birinci günde birlikte duyurulan dört tarih. Her biri geldiğinde ayrı bir changelog girdisidir, bu yüzden hikaye sadece changelog’u okuyanlara dört kez anlatılır.

1. Duyurun. Girdi neyin deprecate edildiğini, nedenini, neyin yerine geçtiğini, ve sunset tarihini söyler. Eski şeyin dokümantasyonu göçe bağlanan bir banner kazanır. Yanıtlar aşağıda açıklanan başlıkları kazanır.
2. Hatırlatın, yarı yolda. İkinci bir girdi, ve eski davranışı hâlâ kullanan her çağırana doğrudan bir mesaj. Bu, kullanım verisine ihtiyaç duyan adımdır: deprecate edilmiş endpoint’i hâlâ kimin çağırdığını listeleyemiyorsanız, bunu yapamazsınız, ve bir sonraki deprecation’dan önce düzeltmeye değer.
3. Tarihten kısa süre önce brownout yapın. Eski davranış için kısa bir pencere boyunca, bir saat veya bir gün, hatalar döndürün, sonra geri yükleyin. Her bildirimi kaçıran çağıranlar hâlâ zaman varken şimdi öğrenir. GitHub, API için şifre kimlik doğrulamasını emekliye ayırmadan önce planlanmış brownout’lar kullandı, ve bu listede en etkili tek adımdır.
4. Sunset. Kaldırın. Yerine geçen hata, yerine geçeni adlandırır ve göç kılavuzuna bağlanır. Hatayı uzun süre yerinde tutun; bir 404 bir çağırana hiçbir şey söylemez.

Bir deprecation bildirimi ne söylemeli?

Bir deprecation bildirimi, neyin gittiğini, ne zaman durduğunu, yerine ne kullanılacağını, ve kimin etkilendiğini söyler. İşte şekli, doldurulmuş:

GET /v1/reports/daily deprecate edildi ve 1 Mart 2027’de çalışmayı durduracak. Aynı verileri stabil bir şema ve sayfalama ile döndüren GET /v2/reports?granularity=day ile değiştiriliyor. Son 30 günde v1 endpoint’ini çağıran 214 entegrasyonu etkiler; sizinki de bunlardan biriyse, bu bildirimi e-posta ile de alacaksınız. Göç kılavuzu: [link]. 1 Mart 2027’ye kadar hiçbir şey değişmiyor. O tarihten itibaren v1 endpoint’i bu girdiye bir bağlantı ile 410 Gone döndürüyor.

Her cümle okuyucunun ihtiyaç duyduğu bir şey taşır. Etkilenen entegrasyonların sayısı her okuyucuya okumaya devam edip etmeyeceğini söyler. “Kadar hiçbir şey değişmiyor” etkilenmeyenlerin sekmeyi kapatmasına izin veren cümledir. Changelog örnekleri sayfası bu şekli tutarlı bir şekilde yazan ekiplerin girdilerini toplar, ve ilk kendinizinkini yazmadan önce üçünü okumaya değer.

Deprecate edilmiş bir endpoint hangi başlıkları göndermeli?

Duyuru gününden itibaren deprecate edilmiş endpoint’ten gelen her yanıtta halefe Deprecation, Sunset ve bir Link gönderin. Deprecation başlığı deprecation’ın yürürlüğe girdiği tarihi taşır; Sunset başlığı endpoint’in yanıt vermeyi durduğu tarihi taşır; Link: <url>; rel="successor-version" yerine ne kullanılacağını gösterir.

HTTP/1.1 200 OK
Deprecation: @1756425600
Sunset: Mon, 01 Mar 2027 00:00:00 GMT
Link: <https://api.example.com/v2/reports>; rel="successor-version"
Link: <https://example.com/changelog/daily-reports>; rel="deprecation"

Çoğu çağıran başlıkları asla kendisi okumayacaktır. Değerleri, bir çağıranın HTTP istemcisinin, gateway’inin veya izlemesinin okuyabilmesidir, ki bu deprecation’ınızı sizin tarafınızda bir sayfa yerine onların tarafında bir uyarıya dönüştürür. Gönderdiğiniz SDK’lar birini gördüğünde bir uyarı kaydetmelidir.

Kime bildirildi, ve bunu nasıl biliyorsunuz?

Bu, sunset’in sakin mi yoksa bir destek olayı mı olacağına karar veren adımdır, ve sadece bir changelog ile yapılması en zor olanıdır. Bir changelog girdisi, changelog’u okuyan herkesi bilgilendirir. Bir deprecation, kodu başarısız olacak belirli insanlara ulaşmalıdır, ve onları bulmanın olağan yolu yarı yolda hatırlatmanın ihtiyaç duyduğu aynı kullanım verisidir: deprecate edilmiş davranışı yakın zamanda çağıran API anahtarları, uygulamalar veya hesaplar.

Çalıştırdığımız döngü: girdi, deprecation’ı ekleyen pull request’ten hazırlanır, bir insan ifadeyi ve tarihi gözden geçirir, ve yayımlandığında girdinin kendisi bildirimdir. Sorunla ilgili widget geri bildirimi veya yerine geçen için talebi, pull request’in kapattığı bir GitHub issue’suna dönüşen herkes, o issue’da gönderildiğini söyleyen ve girdiye bağlantı veren bir yorum alır. Feed ve widget aynı girdiyi diğer herkese sunar, API changelog’daki her diğer girdiyle birlikte. Yapmadığımız şey, bir insan onu yayımlamadan önce deprecation’ın “gönderildi” olmasına izin vermektir; yanlış tarihli bir bildirim, bildirim olmamasından daha kötüdür.

Aracınız ne olursa olsun, sunset gününde cevaplayabilmeniz gereken soru şudur: geçen hafta bunu hâlâ hangi çağıranlar kullanıyordu, ve hangilerine doğrudan söyledik? Cevap “bunun hakkında paylaşım yaptık” ise, sunset hazır değildir.

Deprecate etmek ile versiyonlamak arasındaki fark nedir?

Versiyonlamak, yeni olan varken eski davranışı nasıl kullanılabilir tuttuğunuzdur; deprecation, eskiyi nasıl emekliye ayırdığınızdır. Öncekinin deprecation politikası olmadan yeni bir API versiyonu, ikisini de sonsuza kadar çalıştırmaya bir taahhüttür. Versiyonlama olmadan bir deprecation, gecikmeli bir breaking change’dir. İkisine de ihtiyacınız var, ve versiyon daha kolay olan yarıdır. GraphQL, adlandırmaya değer istisnadır: genellikle artırılacak hiçbir versiyon numarası yoktur, ve GraphQL şema deprecation’ı, paylaşılan tek bir şemanın bunun yerine bir direktifle bir alanı nasıl emekliye ayırdığını ele alır.

FAQ

Deprecate edilmiş bir endpoint tam olarak öncekiyle aynı şekilde çalışmaya devam etmeli mi? Evet, sunset tarihine kadar. İzin verilen tek değişiklikler eklenen başlıklardır ve sona doğru, önceden duyurduğunuz planlı bir brownout’tur.

Emekliye ayrılmış bir endpoint hangi durum kodunu döndürmeli? 410 Gone, yerine geçen ve changelog girdisine işaret eden bir Link başlığı ve bir gövde ile. 404, URL’nin hiç var olmadığını söyler, ki bu yanlış ve yardımcı olmayan bir şeydir.

Bir deprecation dönemi kısaltılabilir mi? Sadece güvenlik için. Eski davranış istismar edilebilirse, bunu söyleyin, dönemi kısaltın, ve changelog’a güvenmek yerine etkilenen her çağırana doğrudan söyleyin.

Bir alanı mı yoksa sadece tüm endpoint’leri mi deprecate etmem gerekiyor? Alanlar, parametreler, enum değerleri, varsayılanlar ve başlıkların hepsi aynı muameleye ihtiyaç duyar, çünkü her biri doğru bir çağıranı bozabilir. Kaldırılmış bir alan en yaygın deprecation türüdür ve en sık atlanan olanıdır.

Bu yazıdaki teknik iddialar bağımsız olarak kontrol edilmedi. Yanlış bir şey varsa bize söyle, düzeltelim.

changeloop'ta ilgili sayfalar: Geliştirici dokümantasyonu, Changelog örnekleri