Blog · Entegrasyon ve mimari

API Testi: Adres Entegrasyonunu Canlıdan Önce Doğrulayın

API testi rehberi: adres entegrasyonunu curl duman testinden mock ve sözleşme testlerine, hata senaryolarından CI'da anahtar yönetimine kadar doğrulayın.

4 dk okuma

Adres verisi kullanan bir özelliği canlıya almadan önce iki şeyi bilmeniz gerekir: kodunuz API'nin döndüğü yanıtı doğru işliyor mu ve işler ters gittiğinde uygulamanız nasıl davranıyor. İyi kurgulanmış bir API testi bu iki soruyu yanıtlar. Bu rehberde elle yapılan hızlı bir kontrolden otomatik testlere kadar adım adım ilerleyeceğiz. Dış servise bağımlı testleri nasıl sınırlayacağınızı ve API anahtarını test ortamında nasıl koruyacağınızı da göreceksiniz.

Test katmanlarını baştan ayırın

Bütün testlerin canlı API'ye gitmesi gerekmez. Hatta çoğunun gitmemesi gerekir. Aşağıdaki ayrım, hem test süresini hem de kota tüketimini kontrol altında tutar.

KatmanNeyi doğrularCanlı API'ye gider miNe zaman çalışır
Duman testiAnahtar ve bağlantı çalışıyor muEvet, tek istekKurulumda, elle
Birim testiKodunuz yanıtı doğru işliyor muHayır, mockHer commit'te
Sözleşme testiKullandığınız alanlar hâlâ yerinde miEvet, az sayıdaZamanlanmış
Hata senaryoları401, 403, 429 gibi durumlarda davranışÇoğunlukla hayırHer commit'te

Adım 1: curl ile hızlı duman testi

İlk kontrol için curl yeterlidir. Anahtarı komut geçmişine düşürmemek için ekrana yazdırmadan okuyun:

read -rs APITURKIYE_KEY && export APITURKIYE_KEY

curl -sS -i "https://api.apiturkiye.com/v1/provinces/34/districts" \
  -H "X-API-Key: $APITURKIYE_KEY"

-i seçeneği yanıt başlıklarını da gösterir. Gözle kontrol edeceğiniz noktalar şunlardır:

  • Durum kodu 200 mü?
  • Content-Type başlığı application/json; charset=utf-8 mi, Türkçe karakterler bozulmadan görünüyor mu?
  • Gövde data dizisiyle mi başlıyor? /v1 yanıtlarında success alanı yoktur. Kodunuzu bu alana göre yazmayın.
  • X-RateLimit-Limit ve X-RateLimit-Remaining başlıkları geliyor mu?

Ardından anahtarı bilerek bozup aynı isteği tekrarlayın. 401 durum kodunu ve invalid_api_key hata kodunu görmelisiniz. Paylaşılan bir terminalde veya CI loglarında -v kullanmaktan kaçının. Bu seçenek istek başlıklarını, yani anahtarınızı da ekrana basar.

Adım 2: Birim testlerde mock API ve kayıtlı yanıtlar

Birim testleri hızlı ve tekrarlanabilir olmalıdır. Ağ, kota ve katalog güncellemeleri bu testleri etkilememelidir. Bu yüzden gerçek API yerine bir mock API kullanılır: HTTP katmanı taklit edilir, kodunuz önceden kaydedilmiş bir yanıtla beslenir.

Örnek yanıtı kaydedin

Gerçek bir yanıtı bir kez alıp test klasörüne koyun. Yalnız gövde kaydedilir, başlıklar ve anahtar dosyaya girmez:

mkdir -p tests/fixtures
curl -sS "https://api.apiturkiye.com/v1/provinces/34/districts" \
  -H "X-API-Key: $APITURKIYE_KEY" > tests/fixtures/districts_34.json

Gerçek kayıtların yanına uç durumlar için elle hazırlanmış küçük dosyalar da ekleyin. Örneğin boş bir data dizisi, meta.nextCursor değeri null olan bir sokak sayfası ya da district alanı null gelen bir autocomplete sonucu. Bu kodlar ve kayıtlar katalog güncellendikçe değişebilir. Testlerde bunları sabit dosyalardan okumanız, testlerin katalog değişikliklerinden etkilenmemesini sağlar.

Test edilecek istemci

# adres_client.py
import os
import requests

BASE_URL = "https://api.apiturkiye.com"

class AdresApiHatasi(Exception):
    def __init__(self, status, code, retry_after=None):
        super().__init__(f"{status} {code}")
        self.status = status
        self.code = code
        self.retry_after = retry_after

def ilceleri_getir(il_kodu, session=requests):
    res = session.get(
        f"{BASE_URL}/v1/provinces/{il_kodu}/districts",
        headers={"X-API-Key": os.environ["APITURKIYE_KEY"]},
        timeout=10,
    )
    if not res.ok:
        try:
            code = res.json().get("error", {}).get("code")
        except ValueError:
            code = None
        raise AdresApiHatasi(res.status_code, code, res.headers.get("Retry-After"))
    return [
        {"stableId": d["stableId"], "code": d["code"], "name": d["name"]}
        for d in res.json()["data"]
    ]

session parametresi testlerde sahte bir nesne vermenizi sağlar. Böylece hiçbir ek kütüphaneye ihtiyaç duymazsınız.

Kayıtlı yanıtla birim testi

# tests/unit/test_adres_client.py
import json
import pathlib
from unittest.mock import Mock

import pytest
from adres_client import ilceleri_getir, AdresApiHatasi

FIXTURES = pathlib.Path(__file__).parent.parent / "fixtures"

def sahte_yanit(status, govde, headers=None):
    res = Mock()
    res.status_code = status
    res.ok = 200 <= status < 300
    res.json.return_value = govde
    res.headers = headers or {}
    return res

@pytest.fixture(autouse=True)
def sahte_anahtar(monkeypatch):
    monkeypatch.setenv("APITURKIYE_KEY", "test-anahtari")

def test_ilceler_kayitli_yanittan_okunur():
    govde = json.loads((FIXTURES / "districts_34.json").read_text(encoding="utf-8"))
    session = Mock()
    session.get.return_value = sahte_yanit(200, govde)

    ilceler = ilceleri_getir(34, session=session)

    assert ilceler and all(i["stableId"] for i in ilceler)
    _, kwargs = session.get.call_args
    assert kwargs["headers"]["X-API-Key"] == "test-anahtari"

Son satıra dikkat edin. Bu satır anahtarın doğru başlıkla gönderildiğini de doğrular. Kimlik doğrulama yalnız X-API-Key başlığıyla yapılır. Authorization başlığı kullanan hatalı bir değişiklik bu testte hemen yakalanır.

Adım 3: Sözleşme testi ile alanları düzenli kontrol edin

Mock'lar kodunuzu korur, ancak kayıtlı yanıt zamanla eskiyebilir. Sözleşme testi bu açığı kapatır. Canlı API'ye az sayıda istek atar ve uygulamanızın gerçekten kullandığı alanların hâlâ beklenen biçimde geldiğini kontrol eder. Bütün yanıtı birebir karşılaştırmayın. Yalnız bağımlı olduğunuz alanları ve türlerini test edin. Bu da bir tür entegrasyon testidir ama dar kapsamlıdır.

// tests/contract/adres.contract.test.mjs
import { test } from "node:test";
import assert from "node:assert/strict";

const canli = process.env.RUN_LIVE_TESTS === "1";
const BASE = "https://api.apiturkiye.com";
const headers = { "X-API-Key": process.env.APITURKIYE_KEY };

test("il listesi sözleşmesi", { skip: !canli }, async () => {
  const res = await fetch(`${BASE}/v1/provinces`, { headers });
  assert.equal(res.status, 200);
  const { data } = await res.json();
  assert.ok(Array.isArray(data) && data.length > 0);
  for (const il of data) {
    assert.equal(typeof il.stableId, "string");
    assert.equal(typeof il.code, "number");
    assert.equal(typeof il.name, "string");
  }
});

test("autocomplete sözleşmesi", { skip: !canli }, async () => {
  const url = new URL(`${BASE}/v1/autocomplete`);
  url.searchParams.set("q", "Kadıköy");
  url.searchParams.set("types", "district");
  url.searchParams.set("limit", "1");
  const res = await fetch(url, { headers });
  assert.equal(res.status, 200);
  const { data } = await res.json();
  assert.ok(data.length > 0, "öneri dönmedi");
  for (const alan of ["type", "stableId", "code", "name", "label", "province"]) {
    assert.ok(alan in data[0], `${alan} alanı eksik`);
  }
});

Bu test, kolayca gözden kaçan bir ayrıntıyı da görünür kılar. İl listesinde code sayısaldır, autocomplete ve doğrulama yanıtlarında ise kodlar metin olarak gelir. Kodları karşılaştırmadan önce tek bir türe çevirmek iyi bir alışkanlıktır.

Adım 4: Hata senaryolarının API testi

Başarılı yol genellikle zaten çalışır. Asıl sorunlar hata yollarında çıkar. Kararlarınızı error.message metnine değil, HTTP durumuna ve error.code değerine göre verin. Hangi kodun hangi tepkiyi gerektirdiği API hata kodları yazısında ayrıntılı olarak anlatılıyor. Burada amaç, bu davranışların testle sabitlenmesidir:

@pytest.mark.parametrize("status,code", [
    (401, "invalid_api_key"),
    (403, "insufficient_scope"),
    (403, "subscription_inactive"),
    (429, "rate_limit_exceeded"),
    (429, "quota_exceeded"),
    (503, "catalog_unavailable"),
])
def test_hata_kodlari_tasinir(status, code):
    session = Mock()
    session.get.return_value = sahte_yanit(status, {"error": {"code": code, "message": "..."}})
    with pytest.raises(AdresApiHatasi) as e:
        ilceleri_getir(34, session=session)
    assert (e.value.status, e.value.code) == (status, code)

def test_hiz_siniri_retry_after_okunur():
    session = Mock()
    session.get.return_value = sahte_yanit(
        429, {"error": {"code": "rate_limit_exceeded", "message": "..."}}, {"Retry-After": "30"}
    )
    with pytest.raises(AdresApiHatasi) as e:
        ilceleri_getir(34, session=session)
    assert e.value.retry_after == "30"

Bu testlerin üzerine uygulama katmanında şu davranışları da doğrulayın:

  • rate_limit_exceeded gelince istemci Retry-After süresi kadar bekliyor mu?
  • quota_exceeded gelince aynı çağrı döngüde yeniden denenmiyor, resetAt zamanı bekleniyor mu?
  • 401 ve 403 durumlarında otomatik tekrar yapılmıyor mu?
  • Doğrulama ucunu kullanıyorsanız valid: false içeren 200 yanıtı bir HTTP hatası gibi ele alınmıyor mu? Bu yanıt, 400 dönen bozuk gövdeden ayrı işlenmeli.

Gerçek bir 429 üretmek için canlı API'yi zorlamayın. Mock ile üretmek hem daha güvenilirdir hem de servise gereksiz yük bindirmez.

Adım 5: Anahtarı CI ortamında gizli değişken olarak tutun

Anahtar depoya, .env dosyasının commit'lenmiş bir kopyasına veya test fixture'larına girmemelidir. .env dosyasını .gitignore listesine ekleyin. CI'da anahtarı platformun gizli değişken (secret) özelliğiyle verin. Anahtarın yaşam döngüsü ve sızıntı durumunda yapılacaklar için API anahtarı yazısına göz atabilirsiniz.

name: testler
on:
  pull_request:
  schedule:
    - cron: "0 4 * * *"
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
      - run: pip install requests pytest
      - run: python -m pytest tests/unit
      - name: Canlı sözleşme testleri
        if: github.event_name == 'schedule'
        env:
          APITURKIYE_KEY: ${{ secrets.APITURKIYE_KEY }}
          RUN_LIVE_TESTS: "1"
        run: node --test tests/contract

Birim testleri anahtar olmadan çalışır. Gizli değişken yalnız canlı adımda tanımlıdır. CI için üretim anahtarından ayrı bir anahtar kullanmak, gerektiğinde onu üretimi etkilemeden iptal etmenizi sağlar. Ancak kota müşteri hesabı bazındadır. Aynı hesaptaki anahtarlar ortak kotayı kullanır, yani ayrı anahtar kotayı ayırmaz.

Adım 6: Canlı API'ye giden testleri sınırlayın

Test trafiği, üretim trafiğinizle aynı kotadan düşer. Bu yüzden canlı testleri bilinçli olarak az tutun:

  • Canlı testleri bir ortam değişkeniyle (RUN_LIVE_TESTS) açıkça etkinleştirin. Varsayılan durum kapalı olsun.
  • Her pull request'te değil, zamanlanmış görevlerde veya sürüm öncesinde çalıştırın.
  • Uç başına bir iki temsilî istekle yetinin. Sayfalı uçlarda limit değerini düşük tutun ve tüm sayfaları gezmeyin.
  • Kasıtlı hata testlerini mock ile yapın. 429 ile reddedilen çağrılar kotadan düşülmez, ancak diğer hata yanıtlarının kotadan ücretsiz olduğunu varsaymayın.

Sözleşme testi beklenmedik biçimde başarısız olursa önce servis durumu sayfasını kontrol edin. Bir kesinti ile gerçek bir alan değişikliğini ayırt etmek, gereksiz kod değişikliklerinin önüne geçer.

Canlıya almadan önce kısa kontrol listesi

  1. curl duman testi 200 döndü, geçersiz anahtarla 401 invalid_api_key görüldü.
  2. Birim testleri kayıtlı yanıtlarla, ağ erişimi olmadan geçiyor.
  3. Sözleşme testi, kullandığınız alanları ve türlerini kontrol ediyor.
  4. 401, 403, 429 ve 503 için davranış testleri var.
  5. Anahtar depoda, loglarda ve fixture dosyalarında yer almıyor.
  6. Canlı testler yalnız açıkça etkinleştirildiğinde çalışıyor.

Uçların tam listesini ve yanıt alanlarını API dokümantasyonunda bulabilirsiniz. Henüz bir anahtarınız yoksa ücretsiz kayıt ile Core paketinden başlayıp bu testleri kendi projenizde kurabilirsiniz.