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.
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.
| Katman | Neyi doğrular | Canlı API'ye gider mi | Ne zaman çalışır |
|---|---|---|---|
| Duman testi | Anahtar ve bağlantı çalışıyor mu | Evet, tek istek | Kurulumda, elle |
| Birim testi | Kodunuz yanıtı doğru işliyor mu | Hayır, mock | Her commit'te |
| Sözleşme testi | Kullandığınız alanlar hâlâ yerinde mi | Evet, az sayıda | Zamanlanmış |
| Hata senaryoları | 401, 403, 429 gibi durumlarda davranış | Çoğunlukla hayır | Her 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
200mü? Content-Typebaşlığıapplication/json; charset=utf-8mi, Türkçe karakterler bozulmadan görünüyor mu?- Gövde
datadizisiyle mi başlıyor?/v1yanıtlarındasuccessalanı yoktur. Kodunuzu bu alana göre yazmayın. X-RateLimit-LimitveX-RateLimit-Remainingbaş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_exceededgelince istemciRetry-Aftersüresi kadar bekliyor mu?quota_exceededgelince aynı çağrı döngüde yeniden denenmiyor,resetAtzamanı bekleniyor mu?401ve403durumlarında otomatik tekrar yapılmıyor mu?- Doğrulama ucunu kullanıyorsanız
valid: falseiçeren200yanıtı bir HTTP hatası gibi ele alınmıyor mu? Bu yanıt,400dö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
limitdeğerini düşük tutun ve tüm sayfaları gezmeyin. - Kasıtlı hata testlerini mock ile yapın.
429ile 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
- curl duman testi
200döndü, geçersiz anahtarla401 invalid_api_keygörüldü. - Birim testleri kayıtlı yanıtlarla, ağ erişimi olmadan geçiyor.
- Sözleşme testi, kullandığınız alanları ve türlerini kontrol ediyor.
401,403,429ve503için davranış testleri var.- Anahtar depoda, loglarda ve fixture dosyalarında yer almıyor.
- 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.