Doğrulama ve Geçerleme: Testte Temel Fark

Bir ekip, spesifikasyonlarına tamamen uyan bir yazılım geliştirebilir ve yine de yanlış ürünü piyasaya sürebilir. Tersi de mümkündür: doğru ürünü hedefleyip hatalarla dolu bir kod tabanı oluşturabilirler. İlk durum doğrulama (verification), ikinci durum geçerleme (validation) problemidir. Bu ayrımı netleştirmek, API kalite sürecinizin gerçekten işe yaramasını sağlar.

Apidog'u bugün deneyin

Bu kılavuzda iki kavramı netleştirecek, farklarını gösterecek ve her birinin Apidog ile API test iş akışında nasıl uygulanacağını anlatacağız.

Doğrulama (Verification) nedir?

Doğrulama şu soruya cevap verir:

Ürünü doğru şekilde mi geliştiriyoruz?

Yani yazılımın kendi spesifikasyonuna, tasarımına ve standartlarına uyup uymadığını kontrol eder. Burada amaç, yapılan işi belgelenmiş beklentiyle karşılaştırmaktır.

Doğrulama şunu sorgulamaz:

Bu spesifikasyon doğru problemi çözüyor mu?

Bunun yerine şunu kontrol eder:

Uygulama, tanımlanan sözleşmeye uyuyor mu?

Tipik doğrulama faaliyetleri:

• Kod incelemeleri ve walkthrough’lar
• Statik analiz ve linting
• Tasarım ve mimari incelemeler
• Şema ve sözleşme kontrolleri
• Birim testleri
• API yanıtlarının şemaya uyup uymadığını kontrol eden assertion’lar

Örneğin spesifikasyon, POST /users endpoint’inin başarılı oluşturma durumunda 201 Created ve Location başlığı döndüreceğini söylüyorsa, doğrulama bunun gerçekten gerçekleşip gerçekleşmediğini kontrol eder.

Basit bir API doğrulama kontrolü şu şekilde düşünülebilir:

pm.test("201 durum kodu dönmeli", function () {
  pm.response.to.have.status(201);
});

pm.test("Location başlığı olmalı", function () {
  pm.response.to.have.header("Location");
});

Bu testler kullanıcının ihtiyacını değil, API’nin sözleşmeye uyup uymadığını doğrular.

Geçerleme (Validation) nedir?

Geçerleme şu soruya cevap verir:

Doğru ürünü mü geliştiriyoruz?

Yazılımın, spesifikasyonda ne yazdığından bağımsız olarak, gerçek kullanıcı ihtiyacını karşılayıp karşılamadığını kontrol eder.

Geçerleme, yapılan işi bir belgeye karşı değil, gerçek kullanım amacına karşı değerlendirir.

Tipik geçerleme faaliyetleri:

• Kullanıcı kabul testleri
• Beta programları
• Kullanılabilirlik testleri
• Uçtan uca iş akışı testleri
• Paydaş demoları ve onayları

Örneğin bir API, OpenAPI spesifikasyonuna tamamen uyabilir. Tüm endpoint’ler doğru durum kodlarını döndürür, şemalar hatasızdır, sözleşme testleri geçer. Ancak istemci geliştiriciler gerçek entegrasyon sırasında API’nin sayfalama modelini kullanışsız buluyorsa veya kimlik doğrulama akışı pratik değilse, API geçerleme açısından başarısızdır.

Geçerleme ve doğrulama: temel farklar

Boyut	Doğrulama (Verification)	Geçerleme (Validation)
Temel soru	Doğru mu inşa ediyoruz?	Doğru şeyi mi inşa ediyoruz?
Karşılaştırılan öğeler	Spesifikasyon, tasarım, standartlar	Kullanıcı ihtiyaçları, gerçek dünya kullanımı
Zamanlama	Sürekli, geliştirme boyunca	Daha sonra, kullanılabilir bir ürün ortaya çıktığında
Tipik yöntemler	İncelemeler, statik analiz, birim testleri, şema kontrolleri	Kabul testleri, beta, uçtan uca testler, demolar
Yön	İçe dönük: artefakt vs. artefakt	Dışa dönük: ürün vs. gerçeklik
Yakalananlar	Hatalar, spesifikasyon sapmaları, sözleşme kayması	Yanlış gereksinimler, kötü uyum, kullanılabilirlik boşlukları
Atlamanın maliyeti	İyi bir spesifikasyona uyan hatalı kod	Yanlış problemi çözen cilalı ürün

İkisi birbirinin yerine geçmez.

• Güçlü doğrulama + zayıf geçerleme = kimsenin istemediği, hatasız çalışan ürün
• Zayıf doğrulama + güçlü geçerleme = doğru fikir, kararsız uygulama

Kısa anımsatıcı:

• Doğrulama: belgeye karşı test
• Geçerleme: amaca karşı test

API testlerinde doğrulama ve geçerleme nasıl ayrılır?

API’lerde bu ayrım özellikle nettir çünkü API’lerin genellikle makine tarafından okunabilir bir sözleşmesi vardır: OpenAPI tanımı, JSON Schema veya benzeri bir API spesifikasyonu.

Bu spesifikasyon doğrulamanın temelidir.

API doğrulaması

Bir API için doğrulama, uygulamanın sözleşmeye uyup uymadığını kontrol eder.

Kontrol etmeniz gerekenler:

• Her endpoint belgelenmiş durum kodlarını döndürüyor mu?
• Yanıt gövdesi belgelenmiş şemaya uyuyor mu?
• Gerekli parametreler gerçekten zorunlu mu?
• Hata formatı dokümantasyondaki yapıyla aynı mı?
• Başlıklar, içerik tipleri ve response formatları beklendiği gibi mi?

Örneğin:

{
  "id": "usr_123",
  "email": "[e-mail]",
  "created_at": "2026-01-15T10:00:00Z"
}

Spesifikasyon id, email ve created_at alanlarını zorunlu tanımlıyorsa, doğrulama bu alanların hem varlığını hem de tipini kontrol eder.

Bu kapsamda REST API'lerinin hangi HTTP durum kodlarını kullanması gerektiğini bilmek önemlidir.

Ayrıca API sözleşme testi doğrudan doğrulama kapsamına girer. Sözleşme testi, üreticinin tüketicilere verdiği API sözünü hâlâ tutup tutmadığını kontrol eder.

Durum kodu, şema ve başlık kontrollerinde kullanılan API iddiaları, doğrulama sürecinin temel yapı taşlarıdır.

API geçerlemesi

Bir API için geçerleme, API’nin tüketicilere gerçekten değer sağlayıp sağlamadığını kontrol eder.

Sorulması gereken sorular:

• Bir istemci gerçek bir iş akışını uçtan uca tamamlayabiliyor mu?
• Login, oluşturma, güncelleme ve silme gibi işlemler birlikte sorunsuz çalışıyor mu?
• Dönen veri istemci geliştiricilerin gerçek ihtiyacını karşılıyor mu?
• Kimlik doğrulama modeli entegrasyon için pratik mi?
• Dokümantasyondaki örnekler gerçek kullanımı yansıtıyor mu?

Tek endpoint üzerinde yapılan şema kontrolü doğrulamadır. Birden fazla isteği gerçek kullanıcı yolculuğuna bağlayan test senaryosu ise geçerlemeye daha yakındır.

Bu yüzden test senaryoları ve test durumları arasındaki farkı bilmek, hangi kalite katmanında çalıştığınızı anlamanızı sağlar.

Apidog bu süreçte nasıl kullanılır?

Apidog, API tasarımı, testi ve dokümantasyonunu aynı çalışma alanında tuttuğu için hem doğrulama hem de geçerleme süreçlerini destekler.

Apidog ile doğrulama

Apidog’da API tasarımı, doğrulamanın referans aldığı sözleşmedir.

Uygulama akışı şu şekilde kurulabilir:

1. API endpoint’lerini ve şemalarını tanımlayın.
2. Her endpoint için beklenen durum kodlarını belirleyin.
3. Yanıt şemalarını testlerde assertion olarak kullanın.
4. Hata yanıtları için ortak format tanımlayın.
5. Testleri CI/CD hattında her commit veya pull request için çalıştırın.

Örnek doğrulama kontrolleri:

• GET /users/{id} isteği 200 dönmeli
• Kullanıcı bulunamazsa 404 dönmeli
• Başarılı response, kullanıcı şemasına uymalı
• Hata response’u standart hata formatını kullanmalı

Bu testleri CI/CD’ye bağlamak, doğrulamayı tek seferlik bir kontrol olmaktan çıkarır. CI/CD'de API testlerini otomatikleştirmek, doğrulamanın sürekli yapılmasını sağlar.

Apidog ile geçerleme

Geçerleme için tek endpoint testleri yeterli değildir. Gerçek kullanıcı akışlarını modellemeniz gerekir.

Örneğin şu akışı bir test senaryosu olarak kurabilirsiniz:

1. Yeni kullanıcı kaydet
2. Kullanıcı ile giriş yap
3. Access token al
4. Yeni kaynak oluştur
5. Kaynağı güncelle
6. Kaynağı sil
7. Silinen kaynağın artık erişilemediğini kontrol et

Bu senaryo, API’nin sadece tek tek endpoint’lerde doğru çalışıp çalışmadığını değil, gerçek bir istemcinin yapacağı işlemleri uçtan uca destekleyip desteklemediğini gösterir.

Apidog raporları da bu ayrımı görünür hale getirir:

• Şema uyuşmazlığı: doğrulama problemi
• Bozuk çok adımlı iş akışı: geçerleme problemi
• Yanlış veya eksik veri modeli: çoğu zaman geçerleme bulgusu
• Beklenmeyen status code: doğrulama bulgusu

Kendi API’nizde hem sözleşme düzeyinde doğrulama hem de iş akışı düzeyinde geçerleme kurmak için Apidog'u indirin.

Gerçek dünya örneği: ödeme API’si

Bir ödeme API’si geliştirdiğinizi düşünün.

Spesifikasyon şöyle olsun:

• POST /payments bir miktar ve para birimi alır
• Başarılı işlemde 201 döner
• Response içinde payment_id bulunur
• Geçersiz para birimi 400 ile reddedilir

Örnek request:

{
  "amount": 19.99,
  "currency": "TRY"
}

Örnek response:

{
  "payment_id": "pay_123"
}

Doğrulama açısından her şey doğru görünebilir:

• Kod incelemesi başarılıdır
• Endpoint 201 döndürür
• Response şemaya uyar
• Geçersiz para birimi 400 döndürür
• Sözleşme testleri geçer

Ancak ilk gerçek istemci entegrasyonu sırasında problem ortaya çıkar.

API, para miktarını kayan noktalı sayı olarak kabul etmektedir. Bu nedenle bazı işlemlerde yuvarlama sorunları oluşur. Örneğin:

0.1 + 0.2
// 0.30000000000000004

Spesifikasyon amount: number demiştir. Uygulama buna uymuştur. Yani doğrulama başarılıdır.

Ama spesifikasyon yanlıştır.

Para değerleri genellikle float olarak değil, en küçük para birimiyle tam sayı olarak modellenmelidir:

{
  "amount_minor": 1999,
  "currency": "TRY"
}

Burada sorun kodun spesifikasyona uymaması değildir. Sorun, spesifikasyonun gerçek kullanım için yanlış tasarlanmış olmasıdır.

Bu bir geçerleme bulgusudur.

Doğrulama şunu söyler:

Kod sözleşmeye uyuyor.

Geçerleme şunu söyler:

Sözleşme gerçek problemi doğru çözmüyor.

Pratik API kalite kontrol listesi

Her API sürümünde iki ayrı kontrol sütunu çalıştırın.

Doğrulama kontrol listesi

Spesifikasyona karşı kontrol edin:

• Her endpoint belgelenmiş durum kodlarını döndürüyor
• Her response kendi şemasına uyuyor
• Gerekli parametreler gerçekten zorunlu
• Hata response’ları belgelenmiş formata uyuyor
• Header ve content type değerleri beklenen şekilde
• Tüm tüketiciye açık endpoint’ler için sözleşme testleri geçiyor
• Testler CI/CD içinde otomatik çalışıyor

Geçerleme kontrol listesi

Amaca karşı kontrol edin:

• Yeni bir istemci temel iş akışını uçtan uca tamamlayabiliyor
• Dönen veriler gerçek istemci sorularını yanıtlıyor
• Kimlik doğrulama akışı gerçek entegrasyon desenlerine uyuyor
• Dokümantasyondaki örnekler gerçek kullanımla eşleşiyor
• API, paydaşların hedeflediği problemi çözüyor
• Uçtan uca senaryolar kritik kullanıcı yolculuklarını kapsıyor

Yalnızca doğrulama geçerse, yanlış tasarımın doğru uygulamasına sahip olabilirsiniz.

Yalnızca geçerleme geçerse, doğru fikri kırılgan bir uygulamayla sunuyor olabilirsiniz.

Güvenli bir API sürümü için ikisi de gerekir.

Sıkça sorulan sorular

Doğrulama mı, geçerleme mi önce yapılır?

Doğrulama daha erken başlar ve geliştirme boyunca sürekli çalışır. Kod, bir spesifikasyon olduğu anda kontrol edilebilir.

Geçerleme ise kullanıcı veya paydaş tarafından değerlendirilebilecek bir ürün ortaya çıktığında anlamlı hale gelir.

Test etmek geçerleme ile aynı şey midir?

Hayır. Test etmek hem doğrulamayı hem de geçerlemeyi kapsar.

• Birim testleri, şema kontrolleri ve sözleşme testleri doğrulamadır.
• Kabul testleri ve uçtan uca iş akışı testleri geçerlemedir.

Yazılım doğrulamadan geçip geçerlemede başarısız olabilir mi?

Evet. Bu oldukça yaygındır.

Uygulama spesifikasyona tam uyar, ancak spesifikasyon yanlış problemi çözer. Bu durumda ürün doğrulanmıştır ama geçerlenmemiştir.

API sözleşme testi hangi kategoriye girer?

API sözleşme testi doğrulamadır.

Çünkü API’nin tüketicilerle yaptığı belgelenmiş anlaşmaya hâlâ uyup uymadığını kontrol eder. Bu anlaşmanın doğru olup olmadığını değerlendirmez. Bu geçerlemenin işidir.

Hangisi daha fazla hata bulur?

Doğrulama genellikle daha fazla sayıda hata bulur çünkü sürekli çalışır ve küçük sapmaları erken yakalar.

Geçerleme daha az sorun bulabilir, ancak bulduğu sorunlar genellikle daha pahalıdır. Çünkü geçerleme hatası çoğu zaman koddan değil, gereksinim veya tasarımın yanlış olmasından kaynaklanır.

Otomasyon ikisini de kapsayabilir mi?

Otomasyon doğrulamayı çok iyi kapsar:

• Şema kontrolleri
• Sözleşme testleri
• Durum kodu assertion’ları
• Header kontrolleri
• CI/CD testleri

Geçerlemeyi tamamen otomatikleştirmek daha zordur çünkü gerçek dünya uyumu hakkında yargı gerektirir. Ancak uçtan uca API iş akışı testleri, geçerlemenin önemli bir bölümünü otomatikleştirir.