Postman Nedir? API Test Aracı Kullanım Rehberi

Bir API'yi tarayıcının adres çubuğuna yapıştırıp denemeye çalışırsanız işin ne kadar çabuk çıkmaza girdiğini görürsünüz. POST isteği gönderemezsiniz, header ekleyemezsiniz, token yönetemezsiniz. Postman tam olarak bu boşluğu dolduran bir masaüstü ve web uygulaması: API isteklerini göndermek, yanıtları incelemek, testler yazmak ve bunların hepsini ekip arkadaşlarınızla paylaşmak için tek bir çalışma alanı sunuyor.

Backend geliştiricisi bir uç noktayı bitirdiğinde curl komutuyla da test edebilir, ama beş farklı endpoint'i, üç farklı ortamı ve on farklı header kombinasyonunu terminalden yönetmek kısa sürede karmaşıklaşır. Postman bu tekrar eden işi görsel bir arayüze taşıyor; istekleri kaydediyor, klasörler halinde gruplandırıyor, gerektiğinde otomatik çalıştırıyor.

Postman Nedir ve Ne İşe Yarar

Postman, API geliştirme sürecinin büyük bölümünü tek çatı altında toplayan bir platform. İstek gönderme, yanıt inceleme, test yazma, dokümantasyon üretme ve ekip içi paylaşım aynı arayüzde bir arada duruyor.

Araç ilk çıktığında sade bir tarayıcı eklentisiydi, zamanla bağımsız bir masaüstü uygulamasına dönüştü. Bugün Windows, macOS ve Linux sürümlerinin yanında, tarayıcı üzerinden çalışan bir web versiyonu da var. Ücretsiz plan bireysel geliştiriciler ve küçük ekipler için genelde yeterli oluyor.

Tipik kullanım şöyle işliyor: backend geliştiricisi yeni bir endpoint yazıyor, Postman'de bir istek oluşturup deniyor, doğru yanıtı aldıktan sonra bu isteği bir koleksiyona ekliyor. Frontend ekibi aynı koleksiyonu açtığında hangi parametrenin zorunlu olduğunu, hangi header'ın gerektiğini örnek üzerinden görüyor. Dokümantasyon ayrı bir belgede değil, çalışan isteklerin kendisinde duruyor.

İstek Göndermek: Method, Header, Body

Bir API isteğinin dört temel parçası var: method, adres, header'lar ve body. Postman'de yeni bir istek açtığınızda bu dördünü ayrı ayrı alanlara yazıyorsunuz; terminaldeki gibi hepsini tek satıra sıkıştırmıyorsunuz.

Örnek olarak bir kullanıcı kaydını çekelim:

GET https://api.example.com/v1/users/42
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Yanıt genelde JSON formatında gelir ve Postman bunu otomatik olarak renklendirip biçimlendirir:

{
  "id": 42,
  "name": "Ahmet Yılmaz",
  "email": "[email protected]",
  "role": "admin",
  "created_at": "2024-11-03T10:15:00Z"
}

Yanıt kodu da üst kısımda görünür: 200 başarılıysa yeşil, 404 bulunamadıysa turuncu, 500 sunucu hatasında kırmızı tonda çıkar. Bu küçük renk kodlaması bile terminaldeki ham çıktıya göre büyük fark yaratır, özellikle art arda onlarca isteği kontrol ederken.

POST isteklerinde body sekmesine geçip raw seçeneğinden JSON formatını seçiyor, göndereceğiniz veriyi yazıyorsunuz. Content-Type header'ını Postman genelde otomatik ekliyor, ama manuel kontrol etmek iyi bir alışkanlık; yanlış content-type yüzünden sunucunun isteği reddettiği durumlar az değil.

HTTP Metodları ve Kullanım Amaçları

Koleksiyonlar ve Ortam Değişkenleriyle Organizasyon

Beş on istekten sonra bunları tek tek saklamak yönetilemez hale gelir. Postman'in koleksiyon (collection) yapısı istekleri klasörler halinde gruplamanıza izin verir; örneğin bir e-ticaret projesinde "Kullanıcılar", "Siparişler", "Ödemeler" gibi ayrı klasörler açabilirsiniz.

Asıl pratik kısım ortam değişkenleri (environments). Aynı isteği geliştirme, test ve canlı ortamda çalıştırmanız gerektiğinde adresi her seferinde elle değiştirmek yerine değişken tanımlarsınız:

# Development ortamı
base_url = https://dev-api.example.com

# Production ortamı
base_url = https://api.example.com

İstek adresini de sabit yazmak yerine değişkenle kurarsınız:

GET {{base_url}}/users

Sol üstteki ortam seçiciden "Development" ile "Production" arasında geçiş yaptığınızda aynı istek otomatik olarak doğru sunucuya gider. Elli isteklik bir koleksiyonda bu tek değişiklik, elli farklı URL'yi tek tek düzenlemekten sizi kurtarır.

Koleksiyonları dışa aktarıp bir JSON dosyası olarak paylaşabilir, ya da Postman workspace üzerinden ekip arkadaşlarınızla doğrudan senkronize edebilirsiniz. Git deposuna dosya olarak da eklenebilir; böylece API sözleşmesindeki değişiklikler kod değişiklikleriyle birlikte izlenebilir.

Otomatik Testler ve CI/CD Entegrasyonu

Postman'in Tests sekmesine JavaScript tabanlı basit kontroller yazabilirsiniz. Bu sayede her istek gönderiminde yanıtın beklediğiniz gibi olup olmadığını otomatik doğrularsınız, elle bakmanıza gerek kalmaz.

En temel örnek yanıt kodunu kontrol etmek:

pm.test("Status code 200 dönüyor", function () {
    pm.response.to.have.status(200);
});

pm.test("Yanıt kullanıcı adı içeriyor", function () {
    var jsonData = pm.response.json();
    pm.expect(jsonData.name).to.eql("Ahmet Yılmaz");
});

Bu testleri tek tek çalıştırmak zorunda değilsiniz. Collection Runner özelliğiyle bir koleksiyondaki tüm istekleri sırayla, tanımladığınız testlerle birlikte çalıştırabilirsiniz. Yüz isteklik bir regresyon kontrolü birkaç dakikada biter.

Daha da önemlisi, Postman'in komut satırı aracı Newman ile bu koleksiyonları CI/CD pipeline'ına sokabilirsiniz. GitHub Actions veya Jenkins üzerinde her commit sonrası API testlerini otomatik tetikleyip, bir endpoint bozulduğunda deploy'u durdurabilirsiniz:

newman run koleksiyon.json -e development.postman_environment.json

Bu satır, elle test etme alışkanlığından kod her değiştiğinde otomatik doğrulama yapan bir sürece geçişi temsil eder. Ekip büyüdükçe bu fark ciddi zaman kazandırır.

Kimlik Doğrulama ve Gizli Bilgi Yönetimi

Gerçek API'lerin büyük kısmı kimlik doğrulama ister ve Postman bunun birkaç yaygın yöntemini hazır sekmelerle destekler: API Key, Bearer Token, Basic Auth, OAuth 2.0. Authorization sekmesinden türü seçip token'ı yapıştırmanız genelde yeterlidir, header'ı elle yazmanıza gerek kalmaz.

Asıl dikkat edilmesi gereken nokta, token'ları koleksiyon içine sabit yazmamak. Bir token'ı isteğin body'sine ya da header'ına doğrudan yazıp koleksiyonu ekip arkadaşınızla paylaşırsanız, o token herkesin erişebileceği bir dosyada dolaşmaya başlar. Doğrusu, token'ı bir ortam değişkenine tanımlayıp isteklerde {{access_token}} şeklinde referans vermektir.

Postman'in "secret" tipi değişkenleri bu konuda ek bir katman sağlar: bu tip işaretlenen değerler arayüzde gizlenir ve koleksiyon dışa aktarıldığında varsayılan olarak dahil edilmez. Yine de paylaşılan bir workspace'te kimin hangi ortamı görebildiğini düzenli kontrol etmek gerekir, çünkü yanlış yapılandırılmış bir erişim izni canlı ortam anahtarının yanlış kişiye ulaşmasına yol açabilir.

Postman'e Alternatif Araçlar Ne Zaman Tercih Edilir

Postman piyasada en yaygın bilinen araç ama tek seçenek değil. Ekibin ihtiyacına göre farklı araçlar daha mantıklı olabilir.

• Insomnia: Daha sade bir arayüz istiyorsanız ve GraphQL ağırlıklı çalışıyorsanız iyi bir alternatif.
• Thunder Client: VS Code içinde kalmak, ayrı bir uygulama açmamak istiyorsanız pratik bir eklenti.
• cURL: Tek seferlik hızlı bir kontrol için hâlâ en pratik yöntem, özellikle sunucu üzerinde terminalden çalışıyorsanız.
• HTTPie: Komut satırında okunabilir çıktı istiyorsanız curl'e göre daha kullanıcı dostu bir seçenek.

Büyük ekiplerde tercih genelde Postman yönünde ağırlaşır, çünkü koleksiyon paylaşımı, workspace yönetimi ve Newman entegrasyonu diğer araçlarda bu kadar olgun değil. REST API kavramlarının genel yapısını netleştirmek isterseniz Microsoft'un REST API tasarım rehberine göz atmak faydalı olur.

Hangi aracı seçerseniz seçin, API testini geliştirme sürecinin sonuna bırakmamak asıl kazandıran alışkanlık. Bir endpoint'i yazar yazmaz denemek, hatayı üretim ortamına sızmadan önce yakalamanın en ucuz yolu.

Yazan Celil Uyanikoglu

Bilgisayar mühendisiyim; 25 yılı aşkın süredir bilgi işlem sektörünün içindeyim. Bu blogu 2020'de, işimde her gün karşılaştığım sorunların çözümlerini bir yere yazmak için açtım: Linux, güvenlik, tarayıcılar, yapay zeka araçları. Yazdığım her rehberi önce kendi bilgisayarımda ya da sunucumda deniyorum; çalıştığını görmediğim adımı yayınlamam. Hatalı ya da eskimiş bir şey görürsen iletişim sayfasından yaz — düzeltirim.