Postman ile API Test Etme ve Dokümantasyon Rehberi

Tarafındankomut
0 Comments

API geliştirme sürecinde en çok vakit kaybettiğimiz nokta genellikle şu soruyu cevaplamaya çalışmaktır: “Bu endpoint gerçekten çalışıyor mu?” Geliştirici ekibiyle koordinasyon sağlarken, bir servisi production’a almadan önce kontrol ederken ya da üçüncü parti bir API ile entegrasyon yaparken Postman hayat kurtarıcı bir araç haline geliyor. Bu yazıda Postman’i sadece basit GET/POST istekleri göndermek için değil, gerçek bir sysadmin ve DevOps iş akışının parçası olarak nasıl kullanabileceğinizi ele alacağım.

Postman Nedir ve Neden Önemlidir

Postman başlangıçta basit bir Chrome eklentisiydi. Bugün ise tam anlamıyla bir API geliştirme platformuna dönüştü. Sadece HTTP istekleri göndermekle kalmıyor, environment yönetimi, otomatik test yazma, CI/CD entegrasyonu ve dokümantasyon oluşturma gibi özellikleri de bünyesinde barındırıyor.

Sysadmin olarak Postman’e ihtiyaç duyduğunuz senaryolar genellikle şunlardır:

  • Yeni kurulan bir servisin REST API’sini doğrulamak
  • Monitoring sisteminize yeni bir webhook eklemek
  • Dahili geliştirme ekibine API dokümantasyonu sağlamak
  • Staging ve production ortamları arasında endpoint davranışlarını karşılaştırmak
  • Rutin API sağlık kontrollerini otomatize etmek

Kurulum ve İlk Yapılandırma

Postman hem masaüstü hem de web tabanlı olarak kullanılabiliyor. Linux üzerinde kurulum oldukça basit:

# Ubuntu/Debian için Snap ile kurulum
sudo snap install postman

# Alternatif olarak Manuel kurulum
wget https://dl.pstmn.io/download/latest/linux64 -O postman.tar.gz
tar -xzf postman.tar.gz -C /opt
sudo ln -s /opt/Postman/Postman /usr/local/bin/postman

# Masaüstü kısayolu oluşturma
cat > ~/.local/share/applications/postman.desktop << EOF
[Desktop Entry]
Name=Postman
Exec=/opt/Postman/Postman
Icon=/opt/Postman/app/icons/icon_128x128.png
Terminal=false
Type=Application
Categories=Development;
EOF

Windows tarafında ise klasik installer ile kurulum yeterli. Ancak büyük ekiplerde çalışıyorsanız Postman’in team workspace özelliğini aktif etmek için hesap açmanızı öneririm. Ücretsiz plan çoğu senaryo için yeterli geliyor.

Collection ve Environment Kavramları

Postman’i verimli kullanmanın temeli bu iki kavramı doğru anlamaktan geçiyor.

Collection, ilgili API isteklerini gruplayarak sakladığınız yapıdır. Bir mikroservise ait tüm endpoint’leri tek bir collection altında toplayabilirsiniz. Environment ise değişken gruplarıdır. Aynı collection’ı farklı ortamlarda (dev, staging, production) çalıştırabilmek için environment’lar kullanılır.

Örnek bir environment kurulumu şöyle görünür. Postman arayüzünde “Environments” sekmesinden yeni bir environment oluşturduğunuzda şu değişkenleri tanımlayabilirsiniz:

  • base_url: https://api-dev.sirketim.com (dev ortamı için)
  • api_key: dev_abc123xyz
  • timeout: 5000
  • user_id: 1001

Production environment’ı için aynı değişkenler farklı değerlerle dolar. Bu sayede collection içindeki her istek {{base_url}}/users/{{user_id}} şeklinde yazılır ve environment değiştirince tüm istekler otomatik güncellenir.

Gerçek Dünya Senaryosu: Dahili Monitoring API’si

Diyelim ki şirketinizin dahili bir sunucu izleme API’si var ve siz bu API’yi test etmekle görevlendirildiniz. API şu endpoint’lere sahip:

  • GET /api/v1/servers – Tüm sunucuları listele
  • POST /api/v1/servers – Yeni sunucu ekle
  • GET /api/v1/servers/{id}/metrics – Sunucu metriklerini getir
  • DELETE /api/v1/servers/{id} – Sunucu kaydını sil

İlk adım olarak authentication header’ını ayarlıyoruz:

# Önce token almak için curl ile test edelim
curl -X POST https://api-dev.sirketim.com/auth/token 
  -H "Content-Type: application/json" 
  -d '{"username": "admin", "password": "supersecret"}' 
  | jq '.access_token'

Bu token’ı Postman’de Collection Level Authorization olarak tanımladığınızda, collection altındaki tüm istekler otomatik olarak bu token’ı kullanır. Authorization sekmesinde “Bearer Token” seçip {{auth_token}} yazmanız yeterli.

Pre-request Script ile Dinamik Token Yönetimi

Token’ın her seferinde elle girilmesi zahmetli. Postman’in Pre-request Script özelliği bu sorunu çözüyor. Collection’ın “Pre-request Script” sekmesine şunu yazabilirsiniz:

// Token süresi dolmuş mu kontrol et
const tokenExpiry = pm.environment.get('token_expiry');
const currentTime = new Date().getTime();

if (!tokenExpiry || currentTime > parseInt(tokenExpiry)) {
    // Yeni token al
    pm.sendRequest({
        url: pm.environment.get('base_url') + '/auth/token',
        method: 'POST',
        header: {
            'Content-Type': 'application/json'
        },
        body: {
            mode: 'raw',
            raw: JSON.stringify({
                username: pm.environment.get('api_user'),
                password: pm.environment.get('api_password')
            })
        }
    }, function(err, response) {
        if (!err && response.code === 200) {
            const jsonResponse = response.json();
            pm.environment.set('auth_token', jsonResponse.access_token);
            // Token'ı 1 saat geçerli say
            pm.environment.set('token_expiry', currentTime + 3600000);
            console.log('Yeni token alindi');
        } else {
            console.error('Token alinamadi:', err);
        }
    });
}

Bu script sayesinde token otomatik olarak yenileniyor ve siz her seferinde elle müdahale etmek zorunda kalmıyorsunuz. Özellikle uzun süreli test session’larında çok işe yarıyor.

Test Yazma: Sadece İstek Atmak Yetmez

Postman’in en güçlü yanlarından biri, her isteğe otomatik test yazabilmenizdir. “Tests” sekmesine JavaScript yazarak response’u doğrulayabilirsiniz.

Sunucu listesi endpoint’i için örnek testler:

// Status code kontrolü
pm.test("Basarili response kodu", function() {
    pm.response.to.have.status(200);
});

// Response time kontrolü
pm.test("Response suresi 500ms altinda", function() {
    pm.expect(pm.response.responseTime).to.be.below(500);
});

// Response body yapısı kontrolü
pm.test("Response bir dizi iceriyor", function() {
    const jsonData = pm.response.json();
    pm.expect(jsonData).to.be.an('array');
    pm.expect(jsonData.length).to.be.greaterThan(0);
});

// Her sunucu objesinin gerekli alanları var mı
pm.test("Sunucu objesi gerekli alanlara sahip", function() {
    const jsonData = pm.response.json();
    jsonData.forEach(function(server) {
        pm.expect(server).to.have.property('id');
        pm.expect(server).to.have.property('hostname');
        pm.expect(server).to.have.property('ip_address');
        pm.expect(server).to.have.property('status');
    });
});

// İlk sunucunun ID'sini bir sonraki istek için sakla
if (pm.response.json().length > 0) {
    pm.environment.set('first_server_id', pm.response.json()[0].id);
    console.log('Server ID kaydedildi:', pm.response.json()[0].id);
}

Bu testler sayesinde API’nin davranışı değiştiğinde anında haberdar olursunuz. Bir geliştirici yanlışlıkla response yapısını kırdığında test başarısız olacak ve sorunu production’a geçmeden yakalayacaksınız.

Newman ile CI/CD Entegrasyonu

Postman collection’larını command line üzerinden çalıştırmak için Newman kullanılır. Bu sayede Jenkins, GitLab CI veya GitHub Actions pipeline’larınıza API testlerini entegre edebilirsiniz.

# Newman kurulumu
npm install -g newman
npm install -g newman-reporter-htmlextra

# Collection'ı export et (Postman arayüzünden JSON olarak indir)
# Sonra Newman ile çalıştır

newman run monitoring-api-collection.json 
  --environment production.postman_environment.json 
  --reporters cli,htmlextra 
  --reporter-htmlextra-export ./test-results/report.html 
  --reporter-htmlextra-title "Monitoring API Test Raporu" 
  --delay-request 200 
  --timeout-request 10000

GitLab CI pipeline örneği:

# .gitlab-ci.yml içindeki ilgili stage
api_tests:
  stage: test
  image: node:18-alpine
  before_script:
    - npm install -g newman newman-reporter-htmlextra
  script:
    - newman run collections/monitoring-api.json
        --environment environments/staging.json
        --reporters cli,junit,htmlextra
        --reporter-junit-export results/junit.xml
        --reporter-htmlextra-export results/report.html
  artifacts:
    when: always
    paths:
      - results/
    reports:
      junit: results/junit.xml
    expire_in: 30 days
  only:
    - merge_requests
    - main

Bu yapıyı kurduğunuzda her merge request’te API testleri otomatik çalışır. Test başarısız olursa merge engellenebilir. Geliştirme ekibine altın değerinde bir geri bildirim mekanizması sağlamış olursunuz.

Mock Server Kullanımı

Bazen backend henüz hazır değilken frontend veya entegrasyon geliştirme yapmak gerekir. Postman’in Mock Server özelliği bu durumda devreye giriyor.

Collection’ınızdaki bir isteğe “Example” ekleyip Mock Server oluşturduğunuzda, Postman size gerçek API gibi davranan bir endpoint URL’si veriyor. Frontend ekibi bu mock URL’yi kullanarak geliştirmeye devam edebiliyor.

Mock response örneği için bir istek üzerinde örnek response tanımlaması:

# Mock server URL'nizi aldıktan sonra test edebilirsiniz
curl -X GET https://xxxxxx.mock.pstmn.io/api/v1/servers 
  -H "x-api-key: YOUR_POSTMAN_API_KEY"

# Beklenen örnek response:
# [
#   {
#     "id": "srv-001",
#     "hostname": "web-server-01",
#     "ip_address": "192.168.1.10",
#     "status": "online",
#     "cpu_usage": 45.2,
#     "memory_usage": 68.7
#   }
# ]

Bu özellik özellikle mikro servis mimarilerinde çok değerli. Bir servis bağımlı olduğu başka bir servisi beklemeden geliştirilmeye devam edebilir.

API Dokümantasyonu Oluşturma

Postman’in dokümantasyon özelliği sysadminler için gerçek bir vakit tasarrufu sağlıyor. Her endpoint’e açıklama, parametre bilgisi ve örnek ekledikten sonra tek tıkla web tabanlı bir dokümantasyon sayfası oluşturabilirsiniz.

İyi bir Postman dokümantasyonu için dikkat edilmesi gerekenler:

  • Her istek için açıklayıcı bir isim ve description yazın
  • Path parametrelerini ve query parametrelerini açıklayın
  • Request body için örnek JSON’lar ekleyin
  • Başarılı ve hata senaryoları için ayrı examples tanımlayın
  • Authentication gereksinimleri collection seviyesinde belirtilmeli

Postman dokümantasyonunu publish ettiğinizde şirket içi wiki’nize ekleyebileceğiniz, her zaman güncel kalan bir URL elde edersiniz. Eski dönemlerin “Word’de API dökümanı” acısından kurtulmuş olursunuz.

Environment Yönetiminde İleri Seviye Teknikler

Büyük bir altyapıda birden fazla ortam ve birden fazla team üyesi olduğunda environment yönetimi karmaşıklaşır. Birkaç pratik öneri:

Hassas bilgileri (şifreler, API key’leri) Postman’in “secret” variable tipinde saklayın. Bu değerler sync edilmez ve ekran görüntülerinde görünmez.

Ortamlar arası geçişi kolaylaştırmak için environment dosyalarını version control’e alın ancak secret değerleri .gitignore ile hariç tutun:

# environments/ klasörü yapısı
environments/
  dev.postman_environment.json       # Secret olmayan değerler
  staging.postman_environment.json   # Secret olmayan değerler
  production.postman_environment.json # Secret olmayan değerler
  .gitignore                         # secret değerleri içeren dosyalar hariç

# .gitignore içeriği
*.secrets.json
*passwords*

CI/CD pipeline’larında secret değerleri environment variable olarak enjekte edebilirsiniz:

# Newman ile environment variable override
newman run collection.json 
  --environment staging.json 
  --env-var "api_key=$SECRET_API_KEY" 
  --env-var "db_password=$SECRET_DB_PASSWORD"

Postman Flows ile API Zinciri Oluşturma

Postman’in görece yeni özelliklerinden biri olan Flows, birden fazla API isteğini görsel olarak zincirlemeni sağlıyor. Karmaşık iş akışlarını test etmek için çok kullanışlı.

Örnek senaryo: Yeni bir sunucu ekle, sonra metriklerini al, sonra threshold aşıldıysa uyarı oluştur. Bu senaryoyu Flows ile görsel olarak modelleyebilir ve otomatik çalıştırabilirsiniz.

Script tabanlı yaklaşımı tercih ediyorsanız Pre-request ve Test script’lerini zincirleyerek benzer sonucu elde edebilirsiniz:

// POST /servers isteğinin Test script'i
pm.test("Sunucu basariyla olusturuldu", function() {
    pm.response.to.have.status(201);
    const response = pm.response.json();
    // Yeni sunucunun ID'sini bir sonraki istek için kaydet
    pm.environment.set('new_server_id', response.id);
    pm.environment.set('test_phase', 'server_created');
});

// Koşullu sonraki adım için
if (pm.response.code === 201) {
    postman.setNextRequest('Get Server Metrics');
} else {
    postman.setNextRequest(null); // Dur
}

Yaygın Hatalar ve Çözümleri

Postman kullanırken sık karşılaşılan sorunlar ve pratik çözümleri:

SSL Sertifika Hataları: Geliştirme ortamlarında self-signed sertifika kullanan endpoint’lere bağlanırken hata alırsınız. Settings üzerinden SSL certificate verification’ı kapatabilirsiniz. Ancak bunu sadece geliştirme ortamında yapın.

CORS Hataları: Postman masaüstü uygulamasında CORS hatası almanız normalde mümkün değil, bu tarayıcı kaynaklı bir kısıtlamadır. Eğer web versiyonunda çalışıyorsanız bu sorunla karşılaşabilirsiniz. Masaüstü uygulamasına geçmek çözümdür.

Büyük Response’ların Yavaş Gösterimi: Çok büyük JSON dönen endpoint’lerde Postman yavaşlayabilir. Bu durumda response’ı raw text olarak görüntüleyin ya da önemli kısmı test script’leriyle çıkarıp console’a yazdırın.

Variable Scope Karışıklığı: Postman’de global, collection, environment ve local olmak üzere dört scope seviyesi var. Öncelik sırası local > environment > collection > global şeklindedir. Beklenmedik değerler görüyorsanız doğru scope’a yazdığınızdan emin olun.

Postman CLI ile Gelişmiş Otomasyon

Postman’in kendi CLI aracı olan Postman CLI (postman-cli), Newman’a alternatif olarak sunuluyor ve Postman ekosistemiyle daha derin entegrasyon sağlıyor:

# Postman CLI kurulumu
curl -o- "https://dl-cli.pstmn.io/install/linux64.sh" | sh

# Login
postman login --with-api-key $POSTMAN_API_KEY

# Collection'ı cloud'dan direkt çalıştır (export gerektirmez)
postman collection run "your-collection-id" 
  --environment "your-environment-id" 
  --reporter cli 
  --bail

# Belirli bir klasörü çalıştır
postman collection run "collection-id" 
  --folder "Smoke Tests" 
  --environment "production-env-id"

Bu yaklaşımın avantajı collection’ı export etmenize gerek kalmaması. Postman cloud’da güncel olan versiyonu direkt çalıştırıyorsunuz. Ekip üyelerinden biri collection’ı güncellediğinde CI/CD sisteminiz otomatik olarak güncel versiyonu kullanıyor.

Sonuç

Postman, başlangıçta sadece “bir API test aracı” gibi görünse de doğru yapılandırıldığında API geliştirme, test otomasyonu ve dokümantasyon süreçlerini ciddi ölçüde iyileştiriyor. Sysadmin perspektifinden bakıldığında en kritik kazanımlar şunlar:

Environment yönetimi sayesinde aynı test setini dev’den production’a kadar güvenle çalıştırabiliyorsunuz. Otomatik token yenileme ve dinamik değişkenler tekrarlayan manuel işlemleri ortadan kaldırıyor. Newman entegrasyonu sayesinde API testleri CI/CD pipeline’ının ayrılmaz bir parçası haline geliyor. Canlı dokümantasyon özelliği ise “en güncel dokümantasyon hangisi” sorusunu tarih oluyor.

Ufak bir uyarıyla bitireyim: Postman’in ücretsiz planı çoğu senaryo için yeterli olmakla birlikte, team collaboration ve gelişmiş mock server özellikleri için ücretli plana ihtiyaç duyabilirsiniz. Açık kaynak tercih ediyorsanız Hoppscotch veya Bruno gibi alternatifler de değerlendirilebilir. Ancak olgunluk ve ekosistem zenginliği açısından Postman hala birkaç adım önde.

Bir yanıt yazın

E-posta adresiniz yayınlanmayacak. Gerekli alanlar * ile işaretlenmişlerdir