Tobias Hoffmann

Posted on Jul 6 • Originally published at apidog.com

Güvenilir API Test Stratejileri: Pratik Kılavuz

Çoğu API hatası egzotik değildir: eksik alan, yanlış durum kodu, yük altında zaman aşımı veya sözleşme kontrol edilmeden gönderilen bozucu değişiklik. Ad-hoc testler bunların bazılarını şans eseri yakalar; iyi tasarlanmış bir API test stratejisi ise bunları sistematik olarak yakalar.

Apidog'u bugün deneyin

Bir API test stratejisi, neyi, hangi katmanda ve teslimat döngüsünün neresinde test edeceğinize dair plandır. Hangi kontrollerin her commit’te, hangilerinin geceleri, hangilerinin sürümden önce çalışacağını belirler. Amaç, minimum bakım maliyetiyle maksimum güvenilir kapsama alanı elde etmektir.

Bir API Test Stratejisi Aslında Ne Anlama Gelir?

Bir strateji, test yazmadan önce dört soruyu yanıtlar.

1. Ne test edilecek?

İş değeri taşıyan uç noktaları ve akışları önceliklendirin.

Örneğin:

Ödeme oluşturma
Kullanıcı kimlik doğrulama
Sipariş durumu sorgulama
Veri güncelleme işlemleri

Bir sağlık kontrolü uç noktası ile ödeme API’si aynı risk seviyesinde değildir. Test önceliğini, uç noktanın kolay test edilmesine göre değil; risk, trafik ve iş etkisine göre belirleyin.

2. Hangi katmanda test edilecek?

Her kontrolü uçtan uca teste çevirmeyin.

Bazı testler tek bir HTTP isteğiyle doğrulanabilir. Bazıları iki veya üç servisin birlikte çalışmasını gerektirir. Her şeyi en üst katmanda test etmek, test takımını yavaş, kırılgan ve bakımı zor hale getirir.

3. Ne zaman çalışacak?

Genel kural:

Hızlı testler: her push / pull request
Daha yavaş entegrasyon testleri: geceleri veya release öncesi
Yük ve güvenlik testleri: planlı veya kritik sürüm öncesi

Hızlı ve yavaş testleri aynı yerde çalıştırmak, ya geri bildirimi yavaşlatır ya da kapsama alanını zayıflatır.

4. Başarı kriteri nedir?

Yalnızca 200 OK kontrolü yeterli değildir.

Bir API testi şunları doğrulamalıdır:

Beklenen HTTP durum kodu
Yanıt şeması
Kritik alan değerleri
Hata mesajı formatı
Yanıt süresi
Yetkilendirme davranışı

Örnek doğrulama:

GET /api/users/42 HTTP/1.1
Host: api.example.com
Authorization: Bearer <token>

Beklenenler:

Durum kodu: 200
id: 42
email: geçerli e-posta formatında
Yanıt gövdesi User şemasıyla uyumlu
Yanıt süresi kabul edilebilir eşik içinde

Bu dört soruyu net yanıtlayabiliyorsanız, API test stratejinizin temeli hazırdır.

Bir Strateji Neden Ad-Hoc Testten Daha İyidir?

Ad-hoc test, bir istek gönderip yanıtı gözle kontrol etmektir. Demo için yeterli olabilir; üretim servisi için değildir.

Tekrarlanabilir değildir

Bir geliştiricinin manuel kontrolünü başka biri aynı şekilde tekrar çalıştıramaz. Bu yüzden regresyonlar tekrar sisteme sızar.

Otomatik test ise her çalıştırmada aynı adımları uygular.

Mutlu yola odaklanır

Manuel testlerde genellikle çalışması beklenen senaryolar denenir.

Ama üretimde sorun çıkaranlar çoğu zaman şunlardır:

Eksik zorunlu alan
Süresi dolmuş token
Yanlış rol veya scope
Çok büyük liste
Bozuk JSON
Sınır değerler

Ölçeklenmez

40 uç nokta ve 5 ortamınız varsa, her sürümde 200 manuel kontrol gerekir. Bu pratik değildir. API büyüdükçe manuel kapsama alanı azalır.

Strateji, tek seferlik otomasyon maliyetini tekrar kullanılabilir kapsama alanına dönüştürür.

API Test Piramidi

API test piramidi, hangi katmanda ne kadar test yazmanız gerektiğini gösterir.

        /\
       /  \      Uçtan uca / iş akışı testleri
      /----\     Az, yavaş, yüksek değerli
     /      \
    /--------\   Entegrasyon / sözleşme testleri
   /          \  Orta sayıda, orta hızda
  /____________\ Birim / tek istek testleri
                Çok, hızlı, ucuz

Alt katman: tek istek kontrolleri

Her test tek bir uç noktayı çağırır ve yanıtı doğrular.

Avantajları:

Hızlıdır
Yazması ucuzdur
Hata ayıklaması kolaydır
CI’da her commit’te çalıştırılabilir

Testlerinizin çoğu bu katmanda olmalıdır.

Orta katman: entegrasyon ve sözleşme kontrolleri

Bu testler şunları doğrular:

Servisler doğru veri şekli üzerinde anlaşıyor mu?
API, veritabanı veya başka bir servisle doğru konuşuyor mu?
Birden fazla sistemden geçen akış beklenen sonucu üretiyor mu?

Tek istek testlerinin yakalayamayacağı hataları yakalarlar, ancak daha yavaştırlar.

Üst katman: uçtan uca iş akışları

Birden fazla uç noktadan geçen tam kullanıcı yolculuklarını test ederler.

Örnek:

Sipariş oluştur
Ödeme yap
Sipariş durumunu kontrol et
Fatura bilgisini doğrula

Bu testler yüksek güven verir, ancak bakım maliyeti yüksektir. Sadece kritik iş akışları için kullanın.

Yaygın hata, piramidi ters çevirmektir: çok sayıda yavaş uçtan uca test, çok az hızlı test. Aynı hatayı daha alt katmanda yakalayabiliyorsanız, testi aşağı taşıyın.

Test Türleri ve Ne Zaman Kullanılacakları

Tam bir API test stratejisi birden fazla test türünü birlikte kullanır.

Fonksiyonel Test

Fonksiyonel test, bir uç noktanın belirtiminde yazdığı davranışı gerçekten sağlayıp sağlamadığını kontrol eder.

Kontrol edilecekler:

HTTP durum kodu
Yanıt şeması
Alan değerleri
Hata formatı
İş kuralı çıktıları

Daha detaylı bilgi için API fonksiyonel testi rehberine bakabilirsiniz.

Örnek:

GET /api/users/42 HTTP/1.1
Host: api.example.com
Authorization: Bearer <token>

Beklenen doğrulamalar:

Durum 200
Gövde User şemasıyla eşleşir
id değeri 42
email geçerli e-posta formatında

Entegrasyon Testi

Entegrasyon testi, API’nizin bağımlılıklarıyla doğru çalıştığını doğrular.

Örnek bağımlılıklar:

Veritabanı
Ödeme sağlayıcı
Mesaj kuyruğu
Aşağı akış servis
Kimlik doğrulama servisi

Fonksiyonel test, mock bağımlılıkla başarılı olabilir. Ancak gerçek servis bağlandığında başarısız olabilir. Entegrasyon testleri bu boşluğu kapatır.

Daha fazla ayrıntı için API entegrasyon testi makalesine bakın.

Regresyon Testi

Regresyon testi, daha önce çalışan davranışların yeni değişikliklerle bozulmadığını kontrol eder.

Burada genellikle yeni test türü yazmazsınız. Mevcut otomatik test takımınızı tekrar çalıştırırsınız.

Ne zaman çalışmalı?

Her commit’te hızlı testler
Pull request sırasında kritik testler
Sürümden önce tam regresyon takımı

Detaylar için regresyon testi rehberine bakabilirsiniz.

Sözleşme Testi

Sözleşme testi, API sağlayıcısı ve tüketicisinin aynı istek/yanıt şekli üzerinde anlaştığını doğrular.

Yakalanan problemler:

Yeniden adlandırılmış alan
Değişen veri tipi
Kaldırılmış uç nokta
Zorunlu hale getirilen yeni alan
Değişen hata formatı

Başka ekipler veya müşteriler API’nizi tüketiyorsa sözleşme testi kritik hale gelir.

Detaylar için API sözleşme testi rehberine bakın.

Yük ve Performans Testi

Yük testi, API’nin eşzamanlı trafik altında nasıl davrandığını ölçer.

Takip edilecek metrikler:

Ortalama yanıt süresi
P95 / P99 yanıt süresi
Hata oranı
Throughput
Darboğaz noktası
Zaman aşımı oranı

Yük testlerini her commit’te çalıştırmayın. Bunları genellikle şu zamanlarda çalıştırın:

Lansman öncesi
Beklenen trafik artışı öncesi
Haftalık veya aylık performans kontrolü
Altyapı değişikliği sonrası

Araç seçenekleri için yük testi araçları yazısına bakabilirsiniz.

Güvenlik Testi

Güvenlik testi, API’nin reddetmesi gereken istekleri gerçekten reddettiğini kontrol eder.

Test edilmesi gerekenler:

Tokensız istekler
Süresi dolmuş token
Yanlış role sahip kullanıcı
Yanlış scope
SQL/NoSQL injection denemeleri
Başka kullanıcının verisine erişim
Hassas alanların yanıt içinde sızması

Hassas veri işleyen her uç nokta için en az kimlik doğrulama ve yetkilendirme testleri yazılmalıdır.

Daha fazlası için API güvenlik testi rehberine bakın.

Test Türleri İçin Çalışma Zamanı

Test türü	Yakalananlar	Ne zaman çalışmalı?
Fonksiyonel	Yanlış durum, şema veya değerler	Her commit
Entegrasyon	Bozulmuş servisler arası akışlar	Her commit veya geceleri
Regresyon	Yeni değişiklikle bozulan mevcut davranış	Her commit ve sürüm öncesi
Sözleşme	Arayüzde bozucu değişiklikler	Sağlayıcıdaki her commit
Yük	Trafik altında yavaşlama ve hata	Lansman öncesi ve planlı
Güvenlik	Kimlik doğrulama, enjeksiyon, veri sızıntısı	Sürüm öncesi ve planlı

Pozitif, Negatif ve Uç Durumlar

Her uç nokta için yalnızca başarılı senaryoyu test etmek yeterli değildir. Üç giriş türünü kapsayın.

Pozitif durumlar

Geçerli giriş gönderilir ve başarılı yanıt beklenir.

Örnek:

POST /api/orders HTTP/1.1
Content-Type: application/json

{
  "customerId": "c_123",
  "quantity": 2
}

Beklenen:

Durum 201
Sipariş kaydı oluşturulur
Yanıtta sipariş kimliği döner

Negatif durumlar

Geçersiz giriş gönderilir ve temiz hata yanıtı beklenir.

Örnekler:

Eksik zorunlu alan → 400
Tokensız istek → 401
Yetkisiz kaynak erişimi → 403 veya 404
Bozuk JSON → 400
Geçersiz enum değeri → 400

Negatif testler, API’lerin en sık hata verdiği alan olan hata yönetimini doğrular.

Örnek:

POST /api/orders HTTP/1.1
Content-Type: application/json

{
  "customerId": "c_123",
  "quantity": -5
}

Beklenen:

Durum 400
Yanıt gövdesinde quantity alanını işaret eden açık bir doğrulama hatası

Eğer bu istek 201 veya 500 döndürüyorsa, mutlu yol testinin yakalayamayacağı gerçek bir hata buldunuz demektir.

Uç durumlar

Geçerli girişlerin sınırları test edilir.

Örnekler:

Boş liste
Maksimum uzunlukta metin
Unicode karakterler
0
Negatif sayı
Çok büyük sayı
Yaz saati uygulaması geçişindeki tarih
Çok sayıda sayfalama sonucu

Pratik kural: her pozitif test için en az bir negatif test yazın.

Test Verileri ve Ortamlar

Testleriniz, çalıştıkları veri ve ortam kadar güvenilirdir.

Özel test verileri kullanın

Üretim verisine karşı test çalıştırmayın. Belirli bir satırın varlığına da bağımlı olmayın.

Daha güvenilir yaklaşım:

Testin ihtiyaç duyduğu veriyi test başında oluşturun.
Test sonunda temizleyin.
Gerekirse bilinen fikstür verisi yükleyin.
Veri üretimini otomatikleştirin.

Gerçekçi ve çeşitli girdiler için API test verileri oluşturma rehberine bakabilirsiniz.

Testleri bağımsız yapın

Bir test, başka bir testin çalışmasına bağımlı olmamalıdır.

Kötü örnek:

Test A kullanıcı oluşturur
Test B, Test A’nın oluşturduğu kullanıcıyı varsayar

Daha iyi örnek:

Her test kendi verisini oluşturur
Gerekli ID veya token senaryo içinde açıkça taşınır
Global paylaşılan duruma güvenilmez

Ortamları izole edin

Ayrı ortamlar kullanın:

Local
CI
Staging
Production

Aynı test takımını farklı ortamlarda çalıştırabilmek için şu değerleri değişkenleştirin:

Base URL
Token
Kullanıcı bilgileri
Feature flag’ler
Ortam özel ayarları

Sanal alan ve tam test ortamı farkı için sanal alan ve test ortamı yazısına bakın.

Değişkenlerle parametreleştirin

Test içinde host veya secret sabit kodlamayın.

Kötü:

https://staging-api.example.com

Daha iyi:

{{baseUrl}}/api/users/{{userId}}

Bu sayede aynı senaryo local, CI ve staging ortamlarında düzenleme yapmadan çalışır.

Sola Kaydırın: Daha Erken Test Edin

Sola kaydırmak, testleri teslimat döngüsünde daha erkene taşımaktır.

Bir hata ne kadar geç bulunursa, düzeltme maliyeti o kadar artar. Tasarım aşamasında yakalanan şema uyuşmazlığı birkaç dakikalık düzeltmedir. Üretimde yakalanan aynı hata olay yönetimine dönüşür.

1. Önce sözleşmeyi tasarlayın

Uç noktayı kodlamadan önce şunları tanımlayın:

Path
Method
Request body
Response body
Durum kodları
Hata formatı
Auth gereksinimleri

Bu sözleşmeden test ve mock üretilebilir.

2. Backend tamamlanmadan mock’a karşı test edin

Frontend veya entegrasyon ekibi gerçek endpoint’i beklemek zorunda değildir.

Şemadan oluşturulan mock sunucu sayesinde tüketiciler kendi taraflarını paralel test edebilir.

3. Her commit’te hızlı kontroller çalıştırın

Saniyeler içinde çalışan fonksiyonel ve sözleşme testleri, geliştiricinin iç döngüsüne ait olmalıdır.

Geliştirici kırmızı testi ne kadar erken görürse, düzeltme o kadar ucuz olur.

Daha fazla detay için API geliştirmede sola kaydırmalı test rehberine bakın.

CI’da API Testlerini Otomatikleştirmek

Bir test stratejisi, otomatik çalışmadığı sürece eksiktir.

Hedef:

Her push işleminde testleri çalıştırmak
Başarısızlıkta merge’ü engellemek
Okunabilir rapor üretmek
CI dashboard’da sonuçları göstermek

Tipik API test pipeline’ı:

Her push işleminde: hızlı fonksiyonel ve sözleşme testlerini çalıştır.
Geceleri veya sürüm öncesi: entegrasyon, uçtan uca, yük ve güvenlik testlerini çalıştır.
Her zaman: JUnit XML gibi makine tarafından okunabilir rapor yayınla.

Minimal GitHub Actions örneği:

name: api-tests

on: [push]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 22

      - name: Run API tests
        run: npm test

Kullandığınız araca göre komut değişebilir. Desen aynıdır:

Kodu checkout et
Runtime kur
Testleri çalıştır
Sıfır olmayan exit code ile build’i başarısız yap
Rapor yayınla

Önbellekleme, secret yönetimi ve raporlama dahil tam uygulama için CI/CD’de API testleri nasıl otomatikleştirilir rehberine bakın.

Apidog Stratejiye Nasıl Uyar?

Bu strateji araç bağımsızdır. API tasarımı, test, mock ve dokümantasyon için farklı araçlar kullanabilirsiniz.

Ancak bunun maliyeti vardır:

Belirtim ayrı yerde kalır
Testler ayrı yerde kalır
Mock ayrı yerde kalır
Dokümantasyon senkron dışına çıkabilir

Apidog, bu parçaları tek bir kaynak etrafında birleştirir:

API sözleşmesini tasarlarsınız
Aynı sözleşmeye karşı test senaryoları yazarsınız
Aynı şemadan mock oluşturursunuz
Dokümantasyonu yayınlarsınız

Böylece sözleşme testi ve sola kaydırmalı test ayrı bir iş olmaktan çıkar; akışın doğal parçası haline gelir.

CI tarafında Apidog CLI, kaydedilmiş test senaryolarını ve test takımlarını headless olarak çalıştırır.

Kurulum:

npm install -g apidog-cli

Kaydedilmiş bir senaryo veya test takımını CI’da çalıştırma:

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t <scenarioOrSuiteId> \
  -e <environmentId> \
  -r cli,html,junit

Parametreler:

--access-token: Çalıştırmayı doğrular. CI secret olarak saklayın.
-t: Çalıştırılacak senaryo, klasör veya test takımı kimliği.
-e: Ortam kimliği. Aynı test takımı farklı ortamda çalışabilir.
-r: Raporlayıcılar. cli, html, json, junit desteklenir.

JUnit çıktısı CI dashboard’unu besler. HTML raporu ise insanlar için okunabilir çıktı sağlar.

Veri odaklı çalıştırma örneği:

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t <scenarioId> \
  -e <environmentId> \
  -d ./data/users.csv \
  -r cli,junit

Ek seçenekler:

Raporu buluta göndermek için --upload-report
Belirli bir dalda çalıştırmak için --branch

Not: Apidog CLI, kaydedilmiş Apidog senaryolarını ve test takımlarını çalıştırır. Etkileşimli istek gönderici veya yük jeneratörü değildir. Performans katmanı için özel bir yük testi aracıyla birlikte kullanın.

Başlangıç Stratejisi Kontrol Listesi

Sıfırdan başlıyorsanız bu sırayla ilerleyin:

[ ] Uç noktaları risk ve trafiğe göre sıralayın.
[ ] En yüksek riskli uç noktalardan başlayın.
[ ] Her kritik uç nokta için pozitif fonksiyonel test yazın.
[ ] Her uç nokta için en az bir negatif test ekleyin.
[ ] Liste, sayı ve serbest metin alanları için uç durum testleri ekleyin.
[ ] Başka ekiplerin veya müşterilerin kullandığı API’ler için sözleşme testleri yazın.
[ ] Birden fazla servisten geçen akışlar için entegrasyon testleri ekleyin.
[ ] Ortam değişkenleri ve secret’ları ayırın.
[ ] Test verilerini otomatik oluşturun veya fikstür olarak yükleyin.
[ ] Testleri birbirinden bağımsız hale getirin.
[ ] Hızlı testleri her push işleminde CI’da çalıştırın.
[ ] Başarısız testte build’i kırın.
[ ] Yavaş testleri geceleri veya sürüm öncesi planlayın.
[ ] JUnit raporu yayınlayın.
[ ] API değiştiğinde testleri gözden geçirin.
[ ] Kaldırılan endpoint’lerin testlerini temizleyin.

İlk günden her şeyi yapmanız gerekmez. En yüksek riskli endpoint’ler için fonksiyonel ve negatif testlerle başlayın, CI’a bağlayın, sonra kapsamı kademeli büyütün.

Sıkça Sorulan Sorular

API test stratejisi ile test planı arasındaki fark nedir?

API test stratejisi, üst düzey yaklaşımdır:

Hangi test türleri kullanılacak?
Hangi katmanda çalışacak?
Ne zaman çalışacak?
Başarı kriterleri ne olacak?

Test planı ise belirli bir sürüm veya özellik için somut listedir:

Hangi endpoint’ler test edilecek?
Hangi senaryolar çalışacak?
Hangi veri kullanılacak?
Hangi ortam hedeflenecek?

Strateji daha kalıcıdır. Test planı sürümden sürüme değişir.

Piramidin her katmanında kaç test olmalı?

Sabit oran yoktur. Önemli olan şekildir.

Genel kural:

En çok test: hızlı tek istek testleri
Daha az: entegrasyon ve sözleşme testleri
En az: uçtan uca iş akışı testleri

Yavaş üst katman testleriniz hızlı alt katman testlerinden fazlaysa, test takımınızı yeniden dengeleyin.

Fonksiyonel testlerim varsa sözleşme testine ihtiyacım var mı?

Evet, özellikle API’nizi başka ekipler veya müşteriler tüketiyorsa.

Fonksiyonel test, endpoint’in doğru davrandığını kontrol eder. Sözleşme testi ise arayüzün tüketicileri bozacak şekilde değişmediğini kontrol eder.

Bir endpoint çalışmaya devam edebilir ama yanıt şekli değiştiği için tüketiciyi bozabilir.

Yük testlerini ne sıklıkla çalıştırmalıyım?

Her commit’te değil.

Yük testlerini şu zamanlarda çalıştırın:

Lansman öncesi
Bilinen trafik artışı öncesi
Haftalık veya aylık performans kontrolü
Altyapı değişiklikleri sonrası
Kritik backend değişiklikleri sonrası

Yük testleri kaynak yoğun olduğu için hızlı CI katmanından ayrı tutulmalıdır.

Tüm stratejiyi CI’da otomatikleştirebilir miyim?

Tekrarlanabilir kısımları evet.

CI’da rahatça otomatikleştirilebilenler:

Fonksiyonel testler
Sözleşme testleri
Regresyon testleri
Birçok entegrasyon testi

Ayrı zamanlanması daha uygun olanlar:

Yük testleri
Geniş güvenlik taramaları
Uzun uçtan uca test takımları

Apidog CLI gibi headless test çalıştırıcılar, kaydedilmiş senaryolarınızı her push işleminde çalıştırarak CI otomasyonunun temelini oluşturur.