Dahili API changelog'ları: diğer ekip için ne değişir

Bu hub’daki diğer her yazı bir API’yi çağıranın şirket dışında olduğunu varsayıyor: bir müşterinin mühendisi, bir ortak, dokümanları kendi başına bulan biri. Birçok API’nin tamamen farklı bir çağıranı var, koridorun karşısındaki veya iki kat öteki bir ekip, ve bu bir changelog’un ona ne borçlu olduğu hesabını değiştiriyor, çünkü bir Slack mesajı ona ulaşır ve genelde hiç destek talebi açılmaz. Çoğu ekip bundan dahili API’lerin changelog’a ihtiyacı olmadığı sonucunu çıkarıyor. Gerçekten ihtiyaç duydukları şey farklı bir changelog.

Dahili bir API’nin changelog’unu genel olandan farklı yapan nedir?

Genel bir API changelog’unun örtük bir kitlesi vardır: o API’nin oluşturduğu tek şeyi kullanan herkes. Dahili bir API’nin kitlesi doğrudan ulaşılabilir, ki bu çoğu genel API changelog’unun var olma nedeninin çoğunu ortadan kaldırır: tek tek iletişime geçilemeyen çağıranlara yayın yapmak. Dahili bir API’ye sahip ekip genelde hangi başka ekiplerin onu çağırdığını, bazen belirli servis seviyesine kadar, tam olarak bilir. Bu, genel bir feed’i değil, hedeflenmiş bir mesajı doğal varsayılan yapar, ve dahili API’lerin çoğu kez hiç changelog’suz kalmasının nedeni de budur: sahip ekip hatırladığı iki üç ekibi bilgilendirir, bunun herkesi kapsadığını varsayarak.

“Bizi çağıran ekiplere haber veririz” neden çöker?

Çünkü çağıranların kümesi hiçbir zaman sahip ekibin hatırladığı kadar küçük veya durağan değildir. Tek bir tüketici için inşa edilen bir servis altı ay sonra hiç duyurulmamış bir entegrasyon üzerinden ikinci bir çağıran kazanır, ve sahip ekibin zihnindeki “bizi kim çağırıyor” listesi kimse fark etmeden yanlış hale gelir. Bu başarısızlık sıradan ve yaygındır, bir kayıt yerine hafızaya güvenmenin varsayılan sonucudur, kimsenin dikkatsiz olduğunun işareti değil. Breaking change nedir bir API değişikliğinin öncelikle breaking sayılıp sayılmayacağına nasıl karar verileceğini ele alır; dahili durum bunun üzerine ikinci, daha zor bir soru ekler: kimin bilgilendirileceğini bilmek.

Dahili bir API’nin genel tarzda bir changelog sayfasına ihtiyacı var mı?

Genelde evet, birincil kanal doğrudan olsa bile. Bir sayfa doğrudan mesaja bağlanacak bir şey verir, böylece bildirim kısa kalabilir (“/v2/accounts’ta breaking change, detaylar burada”) kaydırılıp gidecek bir sohbet mesajında tüm açıklamayı taşımaya çalışmak yerine. Ayrıca yeni bir ekibin, ya da doğrudan mesajı kaçıran bir ekibin, entegrasyonu bozulduğunda ve nedenini anlamaya çalışırken kontrol edebileceği şey haline gelir. Sayfanın cilalı veya herkese açık olması gerekmez; bağlanabilir olması ve onu duyuran Slack thread’inden daha uzun yaşaması gerekir.

Çağıranların listesini gerçekte kim tutar?

Sahip ekip, ve bu kabile bilgisi değil gerçek bir yapı taşı olarak ele alınmalıdır. En ucuz versiyon, API’nin kendi deposundaki bir dosya, her yeni entegrasyon inşa edildiğinde güncellenen, her girişte bir sorumlusu olan kısa bir tüketici servisler listesidir, herhangi bir bağımlılık bildirimiyle aynı disiplin. Alternatif olan her breaking change öncesi soruşturmak, birinin doğru kişiye sormayı unuttuğu o bir sefere kadar işe yarar, ve sessizce bozulan dahili bir API bir ekip için genel bir API’ninkinden daha küçük bir olaydır, ama yine de bir olaydır, genelde API’nin sahibi tarafından değil o ekibin kendi nöbetçisi tarafından keşfedilir.

# consumers.yml
- service: billing-service
  owner: "#team-billing"
  since: 2026-03-01
- service: reporting-pipeline
  owner: "#team-analytics"
  since: 2026-06-14

Böyle bir dosya “kimi bilgilendirmemiz gerekiyor”u bir sorudan bir sorguya dönüştürür. Tam olarak bu sorun için inşa edilmiş araçlar, Backstage’in servis kataloğu gibi, API’leri tanımlanmış tüketicileri olan birinci sınıf varlıklar olarak modeller, aynı nedenle: bir kuruluşun yeterince dahili servisi olduğunda, kimin neyi çağırdığına dair kimsenin hafızası kendi başına doğru kalmaz, ve bir şeyin bu kaydı tutması gerekir. Zaten dahili olarak çalıştırdığınız aracın dokümanları, özel bir tane inşa etmeden önce bakılacak doğru yer genelde budur.

Genel bir changelog’un ihtiyaç duymayacağı, dahili bir girişte ne olmalı?

Daha fazla operasyonel somutluk, çünkü okuyucu aynı altyapı içinde buna göre hareket edecek başka bir mühendistir, bunu bir özet olarak okumayacaktır. Değişikliğin hangi ortamlarda ne zaman canlı olduğu, çünkü dahili servisler genel bir çağıranın hiç görmediği aşamalardan terfi eder. Değişiklik tüketici tarafında bir yapılandırma ya da istemci kütüphanesi güncellemesi gerektiriyor mu, varsa bir komut olarak ifade edilmiş şekilde. Ve, dahili çağıranlar düzeltmeyi genelde doğrudan sahip ekiple koordine edebildiği için, bir destek kanalı yerine isimle belirtilmiş bir kişi: “bir şeyi bozarsa @maria’ya haber ver” dahili bir girişte tamamen makul bir satırdır ve genel bir API changelog’unda tuhaf bir satırdır.

Bu, bir monorepo içindeki bir changelog için de aynı şekilde geçerli mi?

Sorunu değiştirmek yerine keskinleştirir. Monorepo changelog’ları bir paketin ne zaman kendi changelog’una ihtiyaç duyduğunu ele alır; bir monorepo’da birkaç paketten biri olan dahili bir API’nin tüketicilerinin yine de açıkça izlenmesi gerekir, çünkü çağıranlarıyla aynı depoyu paylaşmak, bir şey onlara bakmalarını söylemedikçe bir değişikliği fark edecekleri anlamına gelmez. Repo’daki yakınlık, dikkatteki yakınlıkla aynı şey değildir.

FAQ

Yalnızca dahili bir API’nin tek bir çağıranı varsa changelog’a ihtiyacı var mı? Neredeyse hiç, ve o tek ekibe doğrudan bir mesaj genelde yeterlidir. Birden fazla çağıran olduğunda, veya çağıran listesi sahip ekibi bir kez şaşırttığında changelog kendini kanıtlar, çünkü bu hafızanın tek başına artık güvenilir olmadığının işaretidir.

Dahili API değişiklikleri genel olanlarla aynı incelemeden mi geçmeli? Okuyucu dış bir çağıran değil bir meslektaş olduğu için ifade daha hafif olabilir, ama bir değişikliğin breaking olup olmadığı kararı her iki durumda da aynı özeni hak eder. Dahili bir çağıranın yine de eski davranışa bağımlı üretim kodu vardır.

Hiç izlenmediyse dahili bir API’yi kimin çağırdığı nasıl öğrenilir? Sunucu logları ya da bir service mesh’in trafik verisi, hiç tüketici kaydı tutulmadıysa dürüst cevaptır; bu keşfi bir tanesini başlatma anı olarak ele al, tek seferlik bir temizlik olarak değil.

Bir Slack mesajı yeterli mi, yoksa dahili bir değişiklik yine de resmi bir changelog girişine mi ihtiyaç duyar? Saf olarak eklemeli olmayan her şey için ikisi de. Mesaj zamanında okunan şeydir; giriş, haftalar sonra bir sorunu araştıran ve mesajı hiç görmemiş bir ekibin yine de bulabileceği şeydir.

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 araçları karşılaştırması