API Dokümantasyon ve Test: OpenAPI, Postman ve Contract Testing

Neden API Dokümantasyon Önemlidir?

API yazılımı, sizin sistemleriniz ile diğer uygulamaların iletişim kurmasını sağlar. Hastaneler, işletmeler ve kurumlar kendi sistemlerini entegre etmek istediklerinde, iyi hazırlanmış dokümantasyon olmadan başarılı olamaz.

Düşünün ki bir geliştirici ekibiniz API'nizi kullanmaya çalışıyor. Açık ve anlaşılır belgeler olmadan:

• Entegrasyonun tamamlanması aylar sürebilir
• Yanlış kullanımdan kaynaklı hatalar artar
• Teknik destek maliyetleri yükselir
• Müşteri memnuniyeti düşer

İyi dokümantasyon, öğrenme süresini haftaya, hata oranlarını ise yüzde 60'tan fazla azaltır. Bu, sizin ve müşterilerinizin saatlerce kazanması anlamına gelir.

OpenAPI: Endüstri Standardı

OpenAPI (eski adıyla Swagger), API'ları tanımlamak için dünya çapında kabul edilen bir standarttır. Temel fikir basit: API'nizi yazılı bir spesifikasyonda tarif edersiniz. Bu belgede neler yapılabileceği, hangi bilgilerin gerekli olduğu ve API'nin ne şekilde yanıt vereceği açık şekilde anlatılır.

OpenAPI 3.1, JSON Schema tam desteği ile daha esnek tanımlamalar yapmanıza olanak verir. Bu, karmaşık veri yapılarını doğru şekilde belgelemek anlamına gelir.

OpenAPI Spesifikasyonu Nasıl Yazılır?

OpenAPI spesifikasyonları YAML veya JSON formatında yazılır. Örneğin, bir müşteri yönetim API'sini tanımlarken: API'nin adı, versiyonu ve iletişim bilgileri belirtilir. Hangi sunucularda çalıştığı (üretim ve hazırlık ortamları gibi) tanımlanır. API'nin her endpoint'i (örneğin "müşteri listesini getir" veya "yeni müşteri oluştur") ayrıntılı şekilde açıklanır. Her endpoint için hangi parametrelerin gönderileceği, ne tür yanıt alınacağı ve hangi hata kodlarının mümkün olduğu belirtilir.

Müşteri bilgilerinin formatı tanımlanır: adı, e-postası, telefonu, durumu (aktif/pasif/askıya alınmış) gibi alanlar açıklanır. Kimlik doğrulama yöntemi (JWT token gibi) belirtilir.

Bu spesifikasyon, geliştirici ekibi arasında açık bir "sözleşme" oluşturur. Backend ve frontend ekipleri bu belgeden hareket ederek paralel çalışabilir.

API Geliştirme Yaklaşımları

API geliştirmede iki ana yaklaşım vardır:

Yaklaşım	Avantajlar	Dezavantajlar
API-First	Spesifikasyon önce yazılır, takım anlaşması sağlanır, mock server oluşturulabilir, frontend ve backend paralel geliştirilebilir	Başlangıç maliyeti yüksek, spesifikasyonun kod ile senkronizasyonu zor
Code-First	Hızlı prototipleme, kod her zaman doğru kaynak, otomatik dokümantasyon	İlk başta spesifikasyon olmadan geliştirme yapılır, koordinasyon zor, değişiklikler riskli

Profesyonel ekipler için hibrid yaklaşım en etkilidir: Temel spesifikasyon API-First şekilde yazılır, ardından otomatik araçlar ile güncellenir ve kod ile senkronize kalır.

NestJS ile Otomatik Dokümantasyon

Modern Node.js framework'leri (NestJS gibi), API dokümantasyonunu otomatik olarak oluşturabilir. Geliştirici, kodda özel açıklamalar (dekoratörler) ekler. Framework, bu açıklamalardan otomatik olarak OpenAPI spesifikasyonunu üretir. Bu sistem aynı anda kodunuzu güncellediğinizde dokümantasyonunuz da güncellenir.

Örneğin, bir "müşteri oluşturma" endpoint'ini yazarken, geliştirici belirtir ki: 201 durum kodu döndürülmelidir, e-posta alanı gereklidir, telefon alanı opsiyoneldir. Framework, bu bilgileri otomatik olarak belgeleştirir ve Swagger UI (interactive documentation) arayüzünde görüntüler.

Bu yöntem, belge ile kod arasındaki boşluğu ortadan kaldırır. Her kod değişikliği, dokümantasyonda da yansıtılır.

Postman: İnteraktif API Testi

Postman, geliştiricilerin API'leri manuel olarak test etmesini sağlayan popüler bir araçtır. Bir "koleksiyon" oluşturarak, ekibiniz tüm API endpoint'lerini organize şekilde sunabilir.

Postman koleksiyonu şu bilgileri içerir: Her endpoint'in URL'si ve adı, gerekli parametreler, kimlik doğrulama detayları, örnek veri gönderimi. Koleksiyonda "ortamlar" tanımlanabilir - örneğin test sunucusu, hazırlık sunucusu, üretim sunucusu için farklı URL'ler.

Postman'da yazılabilecek testler: API doğru status kodunu döndürüyor mu? Response'taki veriler doğru formatta mı? Beklenen alanlar var mı? Bu testler otomatik olarak çalıştırılabilir, böylece her değişiklik sonrasında hızlı doğrulama yapılır.

Jest ve Supertest ile Otomatik Testler

Postman manuel testler için harikadır, ancak otomatik ve tekrarlı testler için yazılım mühendisliği araçları kullanılır. Jest (Node.js test framework'ü) ve Supertest (HTTP test kütüphanesi) bu amaç için kullanılır.

Bu araçlar ile yazılabilecek testler:

Bir müşteri oluştururken, doğru bilgiler gönderilirse, 201 status kodunun döndürüldüğünü doğrular. E-posta alanı eksikse, 400 hata kodunun döndürüldüğünü kontrol eder. Yanlış e-posta formatı gönderilirse, API'nin bunu reddettiğini doğrular. Aynı e-postaya sahip iki müşteri oluşturulamayacağını kontrol eder. Müşteri listesi sayfalanmış şekilde geliyorsa, pagination bilgilerinin doğru olduğunu doğrular. Kimlik doğrulama tokeni olmadan istek yapılırsa, 401 hatasının döndürüldüğünü kontrol eder.

Bu testler, yazılımcılar tarafından bir kez yazılır ve sonra her kod değişikliğinde otomatik olarak çalıştırılır. Böylece hata yakalanması dakikalar içinde gerçekleşir, ay sonrası değil.

Contract Testing: Hizmet Sağlayıcı ve Tüketici Anlaşması

Larger sistemlerde, birden fazla ekip birbirinin API'lerini kullanır. Örneğin, Müşteri Yönetim ekibi bir API sağlarken, Faturalandırma ekibi bu API'yi kullanır. İki ekip bağımsız çalışıyorsa, birbirini kırmamak önemlidir.

Contract testing bu sorunu çözer. Müşteri API'si "ben müşteri kimliğini gönderirim, size müşteri adı ve e-postasını döndürürüm" diye bir sözleşme yazabilir. Faturalandırma ekibi bu sözleşmeyi kontrol ederek, API'nin gerçekten bu şekilde çalıştığını doğrular. Herhangi bir taraf bu sözleşmeyi bozarsa, otomatik testler bunu hemen bildirir.

Pact adlı bir araç, bu tür testleri Node.js'te yazmanızı sağlar.

CI/CD Pipeline'a Testleri Entegre Etmek

Profesyonel yazılım ekipleri, GitHub Actions, Jenkins gibi araçlar kullanarak, kodu her değiştiğinde otomatik testleri çalıştırır. Akış şöyledir:

1. Geliştirici, kodun yeni bir sürümünü sunucuya yüklemiş (push)
2. Sistem otomatik olarak tüm testleri çalıştırır - birim testleri, entegrasyon testleri, E2E testleri
3. OpenAPI spesifikasyonunun geçerli olup olmadığı kontrol edilir
4. Contract testleri çalıştırılır
5. Kod kalite analizi yapılır
6. Coverage raporu (kodun yüzde kaçının test edildiği) oluşturulur
7. Tüm testler geçerse, kod yayınlanır; birisi başarısız olursa, geliştirici bilgilendirilir

Bu sistem, sorunları üretim ortamına girmeden öncesinde yakalar. Yazılım hataları ile uğraşmak yerine, geliştirici daha iyi özellikler yazabilir.

API'de Değişiklikleri Takip Etmek

API güncellendiğinde, kullanıcılar hangi değişikliklerin olduğunu bilmelidir. Bir changelog (değişim günlüğü) bu amaçla kullanılır.

Açık bir changelog şunları belirtmelidir:

• Yeni eklenen özellikler
• Var olan özelliklerde yapılan değişiklikler
• Düzeltilen hatalar
• Kaldırılan (deprecated) özellikler ve alternatifleri
• Güvenlik güncellemeleri

Örneğin, "müşteri filtresi parametresi eklendi" veya "phone alanı artık opsiyonel" gibi bilgiler. Böylece kullanan geliştiriciler, kendi kodlarını güncelleyip güncellemeyeceklerine karar verebilirler.

Kaliteli Developer Portal Tasarımı

API'nin başarısı, geliştiricilerin bunu kolayca kullanabilmeleri ile ilişkilidir. İyi bir developer portal şu unsurları içermelidir:

Element	Açıklama
Interactive API Explorer	Swagger UI veya ReDoc ile browser'da API'yi test etme
Code Examples	Node.js, Python, JavaScript, cURL örnekleri
Quick Start Guide	5 dakikalık başlangıç rehberi
Authentication Docs	JWT, OAuth2, API Key gibi auth mekanizmalarının açıklanması
Error Codes Reference	Tüm HTTP status kodları ve anlamları
Rate Limiting Info	Rate limit politikası ve headers
Webhook Documentation	Webhook event'leri ve payload'ları
SDKs & Libraries	Resmi SDK'lar ve topluluk kütüphaneleri
FAQ & Troubleshooting	Sık sorulan sorular ve çözümler
Community Forum	Geliştirici desteği ve tartışma alanı

Uygulamalı Best Practices

API dokümantasyon ve testlerini etkili kılmak için şu uygulamaları izleyin:

Versiyonlama: Her önemli değişiklik ile versiyon numarası güncellenmelidir (1.0.0, 1.1.0, 2.0.0 gibi). Bu, kullanıcılara ne zaman güncelleme yapmaları gerektiğini gösterir.

Tutarlılık: API'deki isimler, veri formatları ve yanıt yapıları tutarlı olmalıdır. Bir yerde "user_name", başka yerde "userName" yazmamalısınız.

Güncellik: Kod her güncellendiğinde, dokümantasyon da güncellenmeli. Eski belgeler, geliştiricileri yanıltır ve zaman kaybettirir.

Örnekler: Her endpoint için gerçek dünya senaryolarından alınan örnekler verilmeli. "müşteri adı giriş" yerine "Ahmet Yılmaz" gibi gerçek örnekler daha faydalı olur.

Hata Belgeleri: API'nin başarısız senaryolarda nasıl davranacağını belirtmeli. "Email zaten var" hatasında hangi mesaj gösterilecek?

Performans Bilgileri: API'nin ne kadar hızlı cevap verdiği, kaç istek bir dakikada kabul edileceği (rate limiting) belirtilmelidir.

Güvenlik: Veriler nasıl korunuyor, hangi bilgiler şifreli iletiliyor, kimler erişebiliyor - bunlar açık olmalıdır.

Sonuç

API dokümantasyon ve testleri, modern işletmelerin temelini oluşturur. Hastaneler, kurumsallar ve e-ticaret siteleri, API'leri kullanarak sistemlerini birbirine bağlarlar. İyi hazırlanmış belgeler ve otomatik testler olmadan:

• Entegrasyonlar ay sürer, haftalar içinde bitmemelidir
• Hatalar üretim ortamında tespit edilir, test aşamasında değil
• Teknik destek masasını dolduran sorular artar
• Müşteri memnuniyeti düşer

Tersine, iyi dokümantasyon ve kapsamlı testler ile:

• Yeni geliştiriciler hızlıca API'yi kullanmaya başlayabilir
• Hatalar otomatik olarak tespit edilir
• Kod değişiklikleri güvenlidir - testler bunu doğrular
• Sistem uzun vadede daha istikrarlı çalışır

OpenAPI spesifikasyonları, Swagger UI, Postman koleksiyonları, Jest/Supertest testleri ve Pact contract testing'i birlikte kullanarak, kurumsal düzeyde API sistemleri oluşturulabilir.

---

Smart Maple Ankara, işletmenizin API geliştirme ihtiyaçlarında profesyonel rehberlik sağlar. Dokümantasyon stratejisi, test yapısı ve CI/CD entegrasyonunda uzman ekibimiz, API projenizin başından sonuna kadar başarılı olmasını sağlar.

smart-maple.com adresini ziyaret ederek API geliştirme hizmetlerimiz hakkında daha fazla bilgi alabilirsiniz.