API dokümanı nedir?

API dokümanı, bir yazılımın başka uygulamalar tarafından nasıl kullanılacağını açıklayan teknik rehberdir. Web API bağlamında hangi uç noktaya hangi HTTP isteğinin gönderileceğini, gerekli parametreleri, kimlik doğrulamayı, dönen yanıt biçimini ve hata durumlarını gösterir. İyi hazırlanmış bir doküman, entegrasyon sırasında tahmin ve ekibe tekrar tekrar sorma ihtiyacını azaltır. API kavramı yalnız HTTP hizmetleriyle sınırlı değildir; bu rehber web API dokümantasyonunu ele alır.

API dokümanı nasıl çalışır?​

Bir HTTP API dokümanı işlemleri yöntem ve yol bilgisiyle tanımlar. Aynı yol üzerinde GET ile okuma, POST ile oluşturma gibi farklı işlemler bulunabilir; her işlem için mutlaka ayrı URL gerekmez. Örneğin bir uygulamadaki kullanıcı listesini almak için şu bilgiler verilebilir:

• HTTP yöntemi: GET
• Adres: /users
• Kimlik doğrulama: Örneğin Bearer token
• Sorgu parametreleri: Sayfalama, arama veya sıralama seçenekleri
• Başarılı yanıt: HTTP durum kodu ve JSON gövdesi
• Hata yanıtları: Yetkisiz erişim, hatalı istek veya bulunamayan kaynak durumları

Doküman yalnızca adres listesinden oluşmaz. İsteğin nasıl kurulacağını, yanıtın hangi alanları içerdiğini ve bu alanların veri tiplerini de açıklamalıdır. Böylece istemci uygulama, örneğin id alanını sayı; email alanını metin olarak işleyebilir.

Somut örnek​

Bir uygulamanın ürün bilgisi döndüren bir API’si olduğunu varsayalım. Dokümanda şu örnek bulunabilir:


Başarılı yanıtın gövdesi şöyle olabilir:


Bu örneğe göre istemci, 42 numaralı ürünü ister ve yanıt geldiğinde ürün adını name alanından, stok durumunu ise available alanından okur. Dokümanda ürün bulunamadığında hangi durum kodunun döneceği ve hata yanıtının yapısı da belirtilmelidir. Örneğin istemci, boş bir yanıt beklemek yerine hatayı kontrollü biçimde gösterebilir.

Bir API dokümanını kullanma adımları​

1. Ön koşulları kontrol edin. Gerekli API anahtarını, erişim iznini, temel adresi ve varsa test ortamını öğrenin. Kimlik doğrulama bilgilerini kaynak koduna sabit olarak yazmayın; yapılandırma veya ortam değişkeni kullanın.
2. İhtiyacınız olan uç noktayı seçin. Aynı işlemi yapan birden fazla yöntem varsa oluşturma, okuma, güncelleme ve silme işlemlerinden hangisinin gerektiğini belirleyin.
3. Örnek isteği küçük bir testle çalıştırın. Önce dokümandaki zorunlu başlıkları ve parametreleri aynen kullanın; isteği başarılı biçimde aldığınızda kendi verilerinizi ekleyin.
4. Yanıt şemasını uygulayın. Başarılı durumun yanında yetkisiz erişim, hatalı veri, bulunamayan kayıt ve sunucu hatası gibi yanıtları da ayrı ele alın.
5. Sınırlamaları inceleyin. Sayfalama, istek kotası, dosya boyutu, zaman aşımı ve sürüm bilgisi belirtilmişse istemcinizi bunlara göre tasarlayın.
6. Entegrasyonu gerçek veriden önce test ortamında doğrulayın. İstek ve yanıt günlüklerinde token gibi gizli bilgileri maskeleyin.

Beklenen başarı, yalnızca HTTP yanıtının alınması değildir; dönen verinin dokümanda tanımlanan şema ile uyumlu olmasıdır. İstek başarısızsa önce yöntemi, temel adresi, kimlik doğrulama başlığını, zorunlu parametreleri ve veri biçimini karşılaştırın. Bunlar doğru olduğu hâlde hata sürüyorsa hata kodu ile birlikte API sağlayıcısının ilgili bölümünü kontrol edin.

Örneğin yalnızca /products adresini yazmak yeterli değildir. Bu adresin hangi HTTP yöntemiyle çağrılacağı, kimlik doğrulamanın nasıl yapılacağı, ürün listesinin hangi alanları içerdiği ve çok sayıda ürün olduğunda sonraki sayfanın nasıl alınacağı da açıklanmalıdır.

Sık yapılan hatalar​

Dokümanı yalnızca URL listesi sanmak: Yöntem, başlık, gövde, yanıt ve hata bilgileri yoksa geliştirici isteği tahmin etmek zorunda kalır.

Tek örneği tam şema sanmak: Örnek JSON yalnız bir olası yanıttır. Zorunlu alanlar, veri tipleri, null kabulü ve olası diğer değerler ayrıca şemada açıklanmalıdır. Bu bilgiler değiştirilirse istemcinin etkilenebileceği açıkça belirtilmelidir.

Hataları yok saymak: Sadece başarılı yanıtı işleyen istemci; süresi dolmuş token, geçersiz veri veya geçici sunucu hatasında kullanıcıya yanlış sonuç gösterebilir.

Sürüm ve değişiklik bilgisini atlamak: API’de geriye dönük uyumsuz değişiklik yapılabiliyorsa hangi sürümün kullanıldığı ve geçiş yönteminin ne olduğu dokümanda belirtilmelidir.

Sık sorulan sorular​

OpenAPI dosyasını görmek çalışan bir API olduğunu kanıtlar mı?​

Hayır. Tanım dosyası servisin sözleşmesini anlatır; sunucuyu kendiliğinden çalıştırmaz. Dokümanın sürümünü, hedef ortamını ve gerçek yanıtını karşılaştırmanız gerekir. Örnekteki example.com adresleri temsildir; canlı ürün API’si değildir.

Dokümandaki Try it out düğmesi her zaman zararsız mı?​

Hayır. Etkileşimli araç gerçek hedefe istek gönderebilir; POST veya DELETE gibi işlemler veriyi değiştirebilir. Sunucu adresini, kimliği ve işlemin etkisini kontrol edin, mümkünse sağlayıcının test ortamını kullanın. Örnek token alanına üretim sırrını düşünmeden yapıştırmayın.