API changelog: neyi yayınlamalı, kim okur

Bir API changelog’u, bir çağıranın fark edebileceği her değişikliğin tarihli kaydıdır; onu yayınlayan ekip için değil, API’ye entegre olan kişiler için yazılır. Bu kitle, onu bir ürün changelog’undan farklı bir belge yapar: okuyucu, kodunun gelecek ay hala çalışıp çalışmayacağına karar veriyordur. Çoğu aynı şekilde başarısız olur, dahili bir release akışının filtrelenmiş bir kopyası olarak; kaldırılan bir alan, bir metin düzeltmesiyle aynı ağırlıkta yan yana durur ve ikisi de okunmaz.

API changelog nedir?

Başka insanların kod yazdığı bir arayüzdeki değişikliklerin herkese açık, tarihli günlüğüdür. Bir şeyin oraya ait olup olmadığına dair yararlı test, değişikliğin dahili olarak ne kadar büyük olduğuyla hiç ilgili değildir. Geçen yıl yazılmış ve o zamandan beri hiç dokunulmamış, doğru bir çağıranın bu yüzden farklı davranıp davranmayacağını sorar. Bu test bazı çok küçük değişiklikleri kabul eder ve bazı çok büyükleri dışlar.

Aşağıdaki her şey çağıranın şirket dışında olduğunu ve bu belge dışında pratikte ulaşılamaz olduğunu varsayar. Çağıran aynı şirketten başka bir ekip olduğunda, hesap kendi ele alışını hak edecek kadar değişir; dahili API changelog’ları bu kitlenin yerine neye ihtiyaç duyduğunu ele alır.

API geçiş kılavuzu nasıl yazılır bu son belgeyi baştan sona ele alır; kısacası, uyumsuz değişiklik girişinin onu değiştirmeye çalışmak yerine bağlantı vermesi gereken şey budur.

Beşi ayrı ömürleri olan ayrı belgelerdir. Bir deprecation bildirimi tarihli bir sözdür ve changelog’a da aittir, ama bir changelog kaydı bir kez yazılır, deprecation ise sunset’ine kadar takip edilir. Bunları birleştirmek, sunset’lerin kaçırılmasının nedenidir.

Tek bir kayda ne girer?

Altı şey, ilk üçü genellikle eksik olanlardır. Değişikliğin kendisi, dahili bileşen yerine istek veya yanıt cinsinden ifade edilmiş. Doğru bir çağıranı bozup bozmadığı. Çağıranın ne yapması gerektiği, “hiçbir şey” dahil. Yürürlüğe girdiği tarih. Etkilenen sürüm veya sürümler. Varsa geçiş kılavuzuna bir bağlantı.

“Accounts endpoint’i iyileştirildi” diyen bir kayıt altısında da başarısız olur. “accounts.type alanı artık daha önce personal döndürdüğü yerde individual döndürüyor; 2 Eylül’den önce oluşturulan hesaplar için mevcut değerler değişmedi; stringi karşılaştırmadığınız sürece işlem gerekmiyor” diyen bir kayıt, altısını da tek cümlede yanıtlar.

Kayıtları departmana göre değil, sonuca göre kategorize edin. Neredeyse tüm değeri üç etiket taşır: breaking, additive ve fixed. Semantic Versioning ilk ikisini zaten kesin şekilde tanımlar, ve kendi tanımlarınızı icat etmek yerine onunkileri ödünç almak, semver bilen bir okuyucunun etiketlerinizi bilmesi anlamına gelir. Keep a Changelog isterseniz daha uzun bir set sunar, ve merkezi kuralı burada başka her yerden daha güçlü geçerlidir: günlük insanlar içindir, ve bir commit başlığı dökümü değildir.

Bir API changelog’u sürüm notlarından nasıl farklıdır?

Sürüm notları ürünün artık ne yapabildiğini anlatır. Bir API changelog’u sözleşmenin artık ne olduğunu anlatır. Aynı yayınlanan iş genellikle her ikisinde de bir kayıt üretir, farklı ifade edilmiş, çünkü kitleler farklı şeylere ihtiyaç duyar: yeni bir dışa aktarma formatı bir kullanıcı için bir özellik, o alana göre dallanan bir çağıran için ise yeni bir enum değeridir.

Pratik sonuç, ikisinin farklı stille aynı akış olamayacağıdır. Yayınladığınız her şeye abone olan bir çağıran sonunda abonelikten çıkacak, ve sonra breaking change’i kaçıracaktır. Tek bir akış yayınlıyorsanız filtreleyin; ikisini yayınlıyorsanız API olanını daraltın ve içine asla bir pazarlama kaydı girmesine izin vermeyin. İki formu yan yana changelog vs sürüm notları içinde karşılaştırıyoruz.

Bir API changelog’u nerede yaşamalı?

Referans dokümantasyonunun yanında, kararlı bir URL’de, her kayıt bir fragment veya kendi yoluyla ayrı ayrı adreslenebilir şekilde. Çağıranlar olay incelemelerinde ve dahili biletlerde kayıtlara bağlantı verir, ve bağlanamayan bir kayıt yerine ekran görüntüsü olarak yapıştırılır.

Bir sayfa olarak da, makine tarafından okunabilir çıktı olarak da yayınlayın. Kayıtlar yapılandırılmış veri haline geldiğinde bir JSON Feed spesifikasyonu’nu izleyen bir JSON akışı ya da bir RSS akışı hiçbir şeye mal olmaz, ve bu, bir müşterinin değişikliklerinizi kendi release sürecine dahil etmesini sağlayan şeydir. Bu ayrıca birinin üzerine bir şey inşa edip etmeyeceğini belirleyen kısımdır. GitHub, REST API sürümlerini aynı nedenle referansın hemen yanında belgeler: sürüm politikası arayüzün bir parçasıdır.

Pratikte iyi bir kayıt nasıl görünür?

Aynı haftadan, yukarıda anlatılan şekilde üç kayıt:

2026-09-02  Breaking  v2
  `POST /invoices` artık müşterinin hesap para birimiyle eşleşmeyen bir
  `currency`'i reddediyor, sessizce dönüştürmek yerine 422 döndürüyor.
  Dönüştürmeye güvenen çağıranlar hesap para birimini göndermeli. Sadece
  v2'yi etkiler; v1, 2027-01-15'teki sunset'ine kadar değişmez.

2026-09-02  Additive  v1, v2
  `Invoice`, fatura ödenene kadar null olan bir `settled_at` zaman
  damgası kazanıyor. İşlem gerekmiyor. Bilinmeyen alanları reddeden
  client'lar güncellenmeli.

2026-08-31  Fixed  v2
  `GET /invoices?status=`, bilinmeyen bir durum için 400 yerine boş bir
  sayfa döndürüyordu. Artık kabul edilen değerlerle 400 döndürüyor.
  Yazım hatası yapan çağıranlar daha önce sıfır sonuç görüyordu, şimdi
  bir hata görüyor.

Üçüncüsü en sık atlanan türdür, çünkü dahili olarak bir hata düzeltmesidir. O boş sayfanın etrafına bir retry kuran bir çağıran için bu bir davranış değişikliğidir, ve kayıt destek biletini önleyen şeydir. Etiket fixed diyor ve gövde bir çağıranın fark edebileceği şeyi söylüyor, ki bu her düzeltmeyi bir breaking change’e şişirmeden günlüğü dürüst tutan ayrımdır.

Çağıranlar buna nasıl abone olur?

Onlara birden fazla kanal verin, çünkü farklı işleri var. Her şeyi isteyen geliştirici için bir akış. Sadece breaking change isteyen kişi için e-posta. Kodun kendisi için yanıt başlıkları, hiç kontrol etmeyi unutmayan tek abone: RFC 8594’te tanımlanan Sunset başlığı, emeklilik tarihini bir client kütüphanesinin loglayabileceği yanıta koyar.

Çoğu ekibin atladığı kanal doğrudan olandır. Geçen hafta değiştirdiğiniz alanı bir çağıran kullandıysa, kim olduğunu bilirsiniz, ve o hesaplara bir e-posta herhangi bir yayından daha değerlidir. Bu, kimsenin talep etmediği bir değişikliğe uygulanan müşteri geri bildirim döngüsünü kapatma ile aynı disiplindir: etkilenen kişilere ayrı ayrı söylenir, geri kalan herkes akışı alır. Bir webhook, güvenmeden önce bilinmesi gereken kendi başarısızlık moduna sahip dördüncü bir kanaldır: webhook changelog’ları orada bir payload değişikliğinin, yeni şekli reddedecek bir çağıran olmadan neden sessizce bozulduğunu ele alır.

Bir breaking change için kayıt nasıl yazılır?

Nedenle değil, bozulmayla başlayın. On kaydı tarayan bir çağıranın, bunun ona iş çıkarıp çıkarmayacağını ilk cümlede bilmesi gerekir. Sonra tarih, etkilenen sürümler, geçiş, ve eski davranış değişmek yerine kayboluyorsa son tarih.

Aynı içeriği deprecation bildirimine, yanıt başlığına ve doğrudan e-postaya, tutarlı ifade edilmiş şekilde koyun, ve dördüne de aynı tarihi verin. Aralarındaki sapma, planlanmış bir değişikliği bir olaya dönüştüren hatadır, çünkü sadece birini okuyan çağıran yanlış tarihe göre hareket eder. Breaking change nedir kararın kendisini kapsar, ve bir API nasıl deprecate edilir sonrasındaki takvimi kapsar.

changeloop’ta, bir API değişikliği pull request birleştirildiğinde bir kayda dönüşür, bir kişi taslağı düzenler ve onaylar, ve kayıt, widget geri bildirimi pull request’in kapattığı GitHub issue’suna dönüşen bir çağırana o issue üzerinden bildirildiği anda akış ve widget üzerinde yayınlanır. Burada önemli olan gözden geçirme adımıdır: bir API changelog’u sözleşmeye dayalı bir belgedir, ve hiçbir taslak bir kişi okumadan bir çağırana ulaşmamalıdır.

FAQ

Her API değişikliği bir changelog kaydına ihtiyaç duyar mı? Doğru bir çağıranın fark edebileceği her değişiklik evet, dahili saydıklarınız dahil. İstek veya yanıt üzerinde gözlemlenebilir etkisi olmayan değişiklikler hayır, ve onları eklemek okuyucuları gözden geçirmeye alıştırır.

API changelog’u dokümanlarda mı, pazarlama sitesinde mi yaşamalı? Dokümanlarda, referansın hemen yanında. Okuyucu genellikle zaten oradadır, ve pazarlama sitesindeki bir changelog, onun için yazılmamış bir kitle kazanma eğilimindedir.

Ne kadar geriye gitmeli? Süresiz. Kayıtlar yıllar sonra olay incelemelerinde alıntılanır, ve budanmış bir günlük o bağlantıları bozar. Budamak yerine sayfalayın.

Her API sürümü için ayrı bir changelog gerekir mi? Hayır, kayıt başına bir sürüm alanı olan tek bir günlük okumak ve aramak daha kolaydır. Sürüme göre filtreleme sayfanın bir özelliğidir, belgeyi bölmek için bir sebep değil.

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