API geçiş kılavuzu nasıl yazılır

API geçiş kılavuzu, uyumsuz bir değişikliği kesintiye değil kontrol listesine dönüştüren belgedir: ne değişti, bu konuda ne yapılmalı, ve ne zamana kadar. Bir changelog girişi uyumsuz bir değişikliği iki cümlede adlandırabilir; geçiş kılavuzu, o iki cümle “bu seni etkiler” dediğinde ve çağıranın tam olarak neyi değiştirmesi gerektiğini bilmesi gerektiğinde gerçekten açtığı şeydir. Girişi kılavuz olmadan yayınlamak, çağıranın uyumsuz bir değişikliği tam da bunu önlemek için yazılmış belge yerine bir destek biletinden öğrenmesinin yoludur.

API geçiş kılavuzu nedir?

Çağıranı bir API’nin eski biçiminden yenisine götüren, adım adım bir belge; değiştirilecek kodu olan biri için yazılır, API’yi hiç kullanıp kullanmayacağına karar veren biri için değil. Bu ayrım önemlidir: bir geçiş kılavuzu mevcut bir entegrasyon ve mevcut üretim trafiği varsayar, bu yüzden geri alma, kısmi geçiş, ve geçişin başarılı olup olmadığının nasıl anlaşılacağını kapsamak zorundadır, bunların hiçbiri ilk entegrasyon kılavuzuna gerek değildir.

Bir geçiş kılavuzu genellikle son ikisi arasında yer alır: bir deprecation bildirimi bir saati başlatır, ve geçiş kılavuzu çağıranın o saat dolmadan önce izlediği şeydir.

Bir değişiklik ne zaman sadece changelog girişi değil, geçiş kılavuzu gerektirir?

Eski ve yeni davranış arasında birden fazla adım olduğunda, veya değişiklik yeterince çağrı noktasını etkilediğinde, çağıran bir açıklamadan çok işlenmiş bir örnekten fayda görür. Uyumsuz bir değişiklik nedir, ve nasıl gönderilir bir değişikliğin uyumsuz olup olmadığına dair testi ele alır; yanıt evetse, ikinci soru düzeltmenin tek satırlık bir düzenleme mi yoksa gerçek bir geçiş mi olduğudur. Yeniden adlandırılmış bir alanı çağıran sadece changelog girişinden halledebilir. Kimlik doğrulama, sayfalama veya hata işlemedeki bir değişiklik neredeyse her zaman bir kılavuzu hak eder, çünkü doğru yedek kod tek cümlelik bir açıklamadan belli değildir.

Bir geçiş kılavuzu neyi içermelidir?

Beş şey, ve herhangi birini atlamak bir kılavuzu çağıranın bir kez okuyup sonra deneme yanılmaya döndüğü bir sayfaya çevirir. Eski kod, bir projede gerçekte görüneceği gibi gösterilmiş. Yeni kod, aynı şekilde gösterilmiş, farkın soyut bir tanımı olarak değil. Hiçbir şey değişmezse ne bozulur, açıkça söylenmiş, çünkü “hiçbir şey” geçerli ve yaygın bir yanıttır ve çağıranın yine de bunu açıkça duyması gerekir. Geçişin işe yarayıp yaramadığını doğrulamanın bir yolu, bir yanıt alanı veya kontrol edilecek bir durum kodu gibi. Ve bir zaman çizelgesi: eski davranış ne zaman çalışmayı bırakır, ve arada her iki biçim de kullanılabilir mi.

## Para birimi alanlarını float'tan integer'a geçirme (v3.0.0)

Önce:
  { "amount": 19.99 }

Sonra:
  { "amount": 1999 }  // en küçük para birimi (kuruş)

Ne değişiyor: `amount` artık hesap para biriminin en küçük biriminde
bir tam sayı. `amount`'ı float olarak okuyan kod, 1 Ekim 2026'dan
itibaren 100 kat çok büyük bir değer okuyacak.

Doğrula: geçişten sonra, 19,99'luk bir ücret `amount: 1999` olarak
okunmalı, `amount: 19.99` olarak değil.

Zaman çizelgesi: v2, 15 Ocak 2027'ye kadar float döndürmeye devam
ediyor. v3, başlangıçtan itibaren tam sayı döndürüyor. Her iki sürüm
de şu anda canlı.

Bu beş şeyin her biri, çağıranın aksi takdirde tahmin etmesi veya desteğe sorması gereken bir soruyu yanıtlar, ve bir geçiş kılavuzunun gerçekte kurtardığı maliyet tam olarak budur.

Kim yazmalı, ve ne zaman?

Değişikliği tasarlayan kişi, gönderildiği anda, bir hafta sonra biletlerden yeniden inşa eden bir destek ekibi değil. Kararı veren kişi, eski davranışın hangi kısımlarına kimsenin güvenmemesi gerektiğini ve hangilerinin kazara bir sözleşme olduğunu bilir; o bağlam olmadan sonradan birinin yazdığı bir kılavuz ya açığı fazla açıklama ya da insanları gerçekten bozan tek uç durumu kaçırma eğilimindedir. Kılavuz ve uyumsuz değişikliği duyuran changelog girişi birlikte yayınlanmalı, giriş onu tekrarlamak yerine kılavuza bağlanmalıdır.

Bu, sürümleme ve API changelog’u ile nasıl ilişkilidir?

Doğrudan: bir geçiş kılavuzu, semantic versioning ve changelog’unuz’daki bir MAJOR girişinin sadece bir cümlede özetlediği şeyin ayrıntılı versiyonudur. Changelog girişi bir değişikliğin uyumsuz olduğunu ve kabaca neyin değiştiğini söyler; geçiş kılavuzu, o girişin taşıması gereken bağlantıdır. API changelog’u: ne yayınlanır ve kim okur geçiş kılavuzunu bir API’nin sürdürdüğü beş belgeden biri olarak listeler, her biri farklı bir soruyu yanıtlar; bu, “A’dan B’ye gerçekte nasıl geçerim” sorusunu yanıtlayan belgedir, ve tam da bu yanıt genellikle bir changelog girişi için çok uzun olduğundan kendi sayfasını hak eder.

Bir geçiş kılavuzu ne kadar süre yayında kalmalı?

En azından eski davranış erişilebilir olduğu sürece, ve idealde ondan sonra da. Üç deprecation bildirimini yok saydıktan sonra on sekiz ay geç geçiş yapan bir çağıran hâlâ kılavuza ihtiyaç duyar, ve eski davranış kapatıldığı gün onu silmek sadece ona en çok ihtiyaç duyanın onu bulamamasını garanti eder. Onu sabit bir URL’de tutun ve sayfayı geri çekmek yerine zaman çizelgesi bölümünü güncelleyin. Stripe’ın kendi yükseltme kılavuzu bu örüntünün herkese açık bir örneğidir: her sürümde güncel tutulan tek bir sayfa, bir sonraki sürüm çıktığı anda eskiyen sürüm başına yeni bir belge yerine. Kendi kılavuzunuz da, bir blog arşivine gömülmek yerine, çağıranın zaten okumakta olduğu dokümanlar kadar bulunabilir bir yeri hak eder.

FAQ

Her uyumsuz değişiklik bir geçiş kılavuzu gerektirir mi? Hayır. Çağıranın sadece changelog girişinden halledebileceği bir değişiklik, açık bir yedeğe sahip tek bir yeniden adlandırılmış alan gibi, ayrı bir kılavuza ihtiyaç duymaz. Birden fazla çağrı noktasını etkileyen veya işlenmiş bir örnek gerektiren bir değişiklik duyar.

Bir geçiş kılavuzu API belgeleriyle mi yoksa changelog’da mı yaşamalı? Belgelerle birlikte, changelog girişinden bağlantı verilerek. Changelog girişi bir abonenin önce gördüğü şeydir; kılavuz, harekete geçmeye karar verdiğinde ihtiyaç duyduğu şeydir, ve çağıranın zaten kullandığı referans materyalinin yanında yer alır.

Bir geçiş kılavuzu ile bir deprecation bildirimi arasındaki fark nedir? Bir deprecation bildirimi bir şeyin kaybolacağını ve ne zamana kadar olduğunu belirtir. Bir geçiş kılavuzu bu konuda ne yapılacağının talimatlarıdır. Bağlantılı bir geçiş kılavuzu olmayan bir deprecation bildirimi, çağırana bunu nasıl karşılayacağını söylemeden bir son tarih verir.

Bir geçiş penceresi sırasında hem eski hem yeni davranış belgelenmeli mi? Evet, mümkünse aynı sayfada, böylece çağıran tam olarak neyin değiştiğini görür, farklı zamanlarda yazılmış iki ayrı belgeden bir araya getirmek yerine.

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