API dokümantasyonu, yazılan ama okunmayan sayfalardan ibaretse, yazılmamıştan beterdir: hem bakım maliyeti ödenmiş hem de kimse faydalanmamıştır. İyi belge, okuyanın ilk beş dakikada ilk başarılı çağrısını yapmasını sağlayan belgedir; gerisi süs. Bu bakış açısı, ne yazacağınızı ve neyi yazmayacağınızı belirler.

Belgenin en dürüst okuyucusu, API'i ilk kez gören bir geliştiricidir: ekibinizin yeni üyesi ya da entegrasyon yapan bir dış partner. İçeridekilerin gözü koddan bilir, belgeyi okumaz; bu yüzden belgeyi yazarken kendinize değil, kodu görmeyen o yabancıya yazın. Uç noktaların listesini ezberletmek yerine iş akışını anlatın: önce sipariş açılır, sonra ödeme onaylanır, bildirim en son işlenir; okuyucu kendini bu hikâyenin içinde bulur.

İlk Beş Dakika: Kopyala-Yapıştır Çalışmalı

Okuyucu belgeye sözdizimi öğrenmeye gelmez; işini halletmeye gelir. "Başlarken" bölümü, gerçek bir anahtarla, gerçek bir adresle, kopyala-yapıştır çalışacak bir örnekle başlamalıdır. Kimlik doğrulaması, ilk istek ve beklenen cevap: bu üçlüyü geçen okuyucu, gerisinin yolunu kendisi bulur.

curl -H "Authorization: Bearer $API_ANAHTARI" \
     https://api.ornek.com/v1/siparisler?durum=bekliyor

Her uç nokta için aynı iskelet kullanılmalıdır: ne yapar, hangi parametreler zorunlu, bir istek, bir başarılı cevap, bir hata cevabı. Hata cevaplarını esgeçen belge, destek ekibine yazılmış bir mektuptur: okuyucu 422 aldığında ne yapacağını bilemez ve size yazar.

Örnekler, Açıklamadan Önce Gelir

Bir parametreyi üç cümleyle anlatmak yerine, doğru ve yanlış kullanımın iki örneğini koyun. Örnek, açıklamanın anlatamadığı şeyi gösterir: tarih biçimi, sıralama davranışı, sayfalama sınırı gibi ayrıntılar çoğu zaman koddan okunur.

{
  "hata": "dogrulama_hatasi",
  "mesaj": "tarih alanı ISO 8601 biçiminde olmalıdır",
  "alan": "tarih"
}

Belgeyi güncel tutmanın en güvenilir yolu, belgeyi koddan üretmektir: OpenAPI şeması koddan çıkarılır, örnekler testlerden gelir. Elle yazılan her tablo, ilk sürümden bir sonra yalan söylemeye başlar.

Doğruluk kadar bütünlük de önemlidir: belgede olmayan bir alan, okuyucuya göre var değildir. Saklı kalan bir parametre, ileride "belgede yazmamıştı" diye geri dönen bir hata kaydı demektir. Gizli davranış yerine belgelenmiş bir istisna yazın; API'inizin tüm yüzü, belgesidir. Aynı ilke versiyon notları için de geçerlidir: kırıcı değişikliği duyuran sayfa, o değişikliğin göç yolunu da göstersin. "v2'de şu alan kaldırıldı" cümlesi, yerine ne konduğunu söylemiyorsa belge değil, itiraftır.

Güncel Tutmak Bir Görevdir, İyi Niyet Değil

Belge, kodla birlikte değişen bir üründür. Sözleşmeyi değiştiren her değişiklik, belgeyi değiştiren görevi beraberinde taşır; bunu kod inceleme kontrol listesine yazmak gerekir. Aksi hâlde belge sürüm 2'yi anlatırken API sürüm 3'e hizmet eder ve okuyucunun güveni bir kez kırıldığında geri gelmez. Güncelliği sağlamanın en pratik yolu, örneklerin otomatik testlerde çalıştırılmasıdır: testi geçen örnek, belgelenen davranışın hâlâ geçerli olduğunun kanıtıdır.

Dokümantasyonun kültürü, okuyucudan gelir: hiçbir sayfa, onu okuyan ve geri bildiren bir geliştirici olmadan bitmiş sayılmaz. Geri bildirim kanalını belgenin altına koyun, düzeltmeleri de kod incelemesiyle aynı ciddiyetle birleştirin. Okuyan olmayan sayfa, yazılmamış sayfadır.

Bir de ölçmeyi ihmal etmeyin: belgenizin en çok okunan sayfası, ekibin en çok soru aldığı uç noktadır. O sayfaya yatırım yapın; örneklerini çoğaltın, hata tablosunu genişletin. Dokümantasyon da bir üründür; kullanım verisi olmadan yazılan her sayfa, tahmine dayanır.