Blog · Entegrasyon ve mimari

API Önbellekleme: Adres Listeleri ve Veri Sürümü

API önbellekleme ile il, ilçe ve mahalle listelerini önbelleğe alın; /v1/meta ile katalog sürümünü izleyip önbelleği doğru zamanda yenileyin.

4 dk okuma

Adres formlarında aynı listeler tekrar tekrar istenir. İl listesi her kullanıcı için aynıdır ve İstanbul'un ilçeleri gün içinde değişmez. Bu listeleri her form açılışında API'den yeniden çekmek gecikmeyi artırır ve paket kotanızı gereksiz yere tüketir. API önbellekleme bu tekrarı ortadan kaldırır. Tek zor nokta, önbelleğin ne zaman eskidiğini bilmektir. Bu yazıda hangi adres listelerinin önbelleğe uygun olduğunu, önbelleği hangi olaylarda yenilemeniz gerektiğini, katalog sürümünü /v1/meta ile nasıl izleyeceğinizi ve stableId kullanımının sürüm değişikliklerinde neden işinizi kolaylaştırdığını ele alıyoruz.

Hangi adres listeleri önbelleğe uygun?

Önbellek kararı iki soruya dayanır: Veri ne sıklıkla değişiyor ve kaç farklı anahtar oluşuyor? Adres hiyerarşisinin üst katmanları hem az değişir hem de sınırlı sayıda anahtar üretir. Alt katmanlara indikçe kayıt sayısı artar ve önbelleği isteğe bağlı doldurmak daha mantıklı hâle gelir.

UçÖnbellek uygunluğuÖnerilen yaklaşım
GET /v1/provincesÇok yüksekTek anahtar. Katalog sürümü değişene kadar saklayın.
GET /v1/provinces/{code}/districtsÇok yüksekİl başına bir anahtar. 81 il ve 973 ilçe küçük bir veri hacmidir.
GET /v1/districts/{code}/neighborhoodsYüksekİlçe başına bir anahtar. Liste tek yanıtta tam gelir; tamamını saklayın.
GET /v1/neighborhoods/{code}/streetsOrtaMahalle ilk istendiğinde tüm sayfaları cursor ile toplayıp saklayın.
GET /v1/streets/{code}/buildingsDüşük–ortaYalnız istenen sokakları, daha kısa bir süreyle saklayın.
GET /v1/autocompleteDüşükSorgu çeşitliliği çok yüksektir. En fazla kısa ömürlü bir önbellek kullanın.
POST /v1/addresses/validateUygun değilSonuç, gönderilen adrese ve aktif katalog sürümüne bağlıdır.

İki ayrıntı sık atlanır. Mahalle listesi tek yanıtta tamamen döner. Bu listeyi önbelleğe alırken ilk 100 kayıtla sınırlamayın. Aynı mahalle adı farklı yerleşimlerde bulunabileceği için önbellekteki kayıtları ada göre tekilleştirmeyin; kimlik olarak code veya stableId kullanın.

Önbelleği ne zaman yenilemeli?

Yalnız süreye dayalı bir önbellek iki yönden hata yapar. Süre uzunsa katalog güncellendikten sonra eski veri sunarsınız. Süre kısaysa veri değişmediği hâlde gereksiz istek atarsınız. Daha sağlam bir düzen üç tetikleyiciyi birlikte kullanır:

  1. Katalog sürümü değişti. Asıl yenileme sinyali budur. Sürüm değiştiğinde önbellekteki tüm adres listeleri eski sayılır.
  2. Güvenlik süresi (TTL) doldu. Sürüm kontrolü bir sebeple aksarsa, kayıtların süresiz kalmasını bu üst sınır engeller.
  3. Hata durumunda bayat veriye düşme. 503 catalog_unavailable veya 429 yanıtı aldığınızda elinizdeki son geçerli listeyi sunmak, kullanıcıya hata göstermekten genellikle daha iyidir.

429 yanıtlarında Retry-After başlığına uyun ve isteği hemen tekrarlamayın. Bu konunun ayrıntıları 429 hatası rehberinde anlatılıyor. 401 ve 403 yanıtları bayat veriyle gizlenmemelidir. Bu durumlar anahtar, yetki veya paket sorununa işaret eder ve düzeltilmesi gerekir.

Veri sürümünü /v1/meta ile izlemek

GET /v1/meta aktif katalogun meta verisini döner. Önbelleği bu uçla ilişkilendirmenin en basit yolu, uca belirli aralıklarla istek atıp yanıtın değişip değişmediğine bakmaktır. Değişiklik varsa adres önbelleğini geçersiz sayarsınız.

curl "https://api.apiturkiye.com/v1/meta" -H "X-API-Key: apt_live_..."

Aşağıdaki Node.js örneği (Node 18 ve üzeri) /v1/meta yanıtının data alanından kısa bir parmak izi üretir. Her önbellek kaydına bu parmak izini ekler. Parmak izi değiştiğinde kayıtlar kendiliğinden geçersiz olur. Kontrol aralığı ve TTL değerleri örnek amaçlıdır; bunları kendi ihtiyacınıza göre ayarlayın.

import crypto from "node:crypto";

const BASE = "https://api.apiturkiye.com";
const API_KEY = process.env.APITURKIYE_KEY;

const TTL_MS = 24 * 60 * 60 * 1000;        // güvenlik süresi
const CHECK_INTERVAL_MS = 15 * 60 * 1000;  // sürüm kontrol aralığı

const cache = new Map(); // path -> { data, version, expiresAt }
let catalogVersion = null;
let lastCheck = 0;

async function apiGet(path) {
  const res = await fetch(BASE + path, { headers: { "X-API-Key": API_KEY } });
  if (!res.ok) {
    const body = await res.json().catch(() => ({}));
    const err = new Error(`HTTP ${res.status}`);
    err.status = res.status;
    err.code = body.error?.code;
    err.retryAfter = res.headers.get("Retry-After");
    throw err;
  }
  return res.json();
}

async function currentCatalogVersion() {
  const now = Date.now();
  if (catalogVersion && now - lastCheck < CHECK_INTERVAL_MS) return catalogVersion;
  try {
    const body = await apiGet("/v1/meta");
    catalogVersion = crypto
      .createHash("sha256")
      .update(JSON.stringify(body.data))
      .digest("hex")
      .slice(0, 16);
  } catch (err) {
    if (!catalogVersion) throw err; // hiç sürüm bilgisi yoksa hatayı yükselt
    // aksi hâlde bilinen sürümle devam et
  }
  lastCheck = now;
  return catalogVersion;
}

export async function cachedList(path) {
  const version = await currentCatalogVersion();
  const entry = cache.get(path);
  if (entry && entry.version === version && entry.expiresAt > Date.now()) {
    return entry.data;
  }
  try {
    const { data } = await apiGet(path);
    cache.set(path, { data, version, expiresAt: Date.now() + TTL_MS });
    return data;
  } catch (err) {
    if (entry && (err.status === 429 || err.status === 503)) return entry.data; // bayat veri
    throw err;
  }
}

// Kullanım
const provinces = await cachedList("/v1/provinces");
const districts = await cachedList("/v1/provinces/34/districts");

Parmak izi yaklaşımı, yanıtın alan yapısına bağımlı olmadığı için hemen çalışır. Ancak /v1/meta yanıtı her istekte değişen bir alan içeriyorsa (örneğin bir zaman damgası) bu yöntem önbelleği gereğinden sık geçersiz kılar. Bu durumda karşılaştırmayı yalnız sürümü temsil eden alanla yapın. Alan adlarını API dokümantasyonundaki /v1/meta şemasından doğrulayın.

Sürüm bilgisini başka kaynaklardan da okuyabilirsiniz

  • Anahtarınızda datasets:read yetkisi varsa GET /v1/datasets/current yanıtındaki data.datasetVersion alanı, UUID biçiminde açık bir sürüm kimliği verir.
  • POST /v1/addresses/validate başarılı yanıtında meta.datasetVersion döner. Bu değer bilinen sürümünüzden farklıysa sürüm kontrolünü planlanan zamanı beklemeden tetikleyebilirsiniz.

Aşağıdaki Python örneği sürümü /v1/datasets/current üzerinden okur. Ayrıca cursor sayfalamalı cadde/sokak listesini mahalle bazında toplayıp önbelleğe alır.

import os
import time
import requests

BASE = "https://api.apiturkiye.com"
HEADERS = {"X-API-Key": os.environ["APITURKIYE_KEY"]}
TTL = 24 * 3600
_cache = {}  # anahtar -> (sürüm, son_geçerlilik, veri)


def get_json(path, params=None):
    res = requests.get(BASE + path, headers=HEADERS, params=params, timeout=10)
    res.raise_for_status()
    return res.json()


def dataset_version():
    # datasets:read yetkisi gerektirir; her istekte değil, aralıklarla çağırın
    return get_json("/v1/datasets/current")["data"]["datasetVersion"]


def all_streets(neighborhood_code):
    items, cursor = [], None
    while True:
        params = {"limit": 100}
        if cursor:
            params["cursor"] = cursor
        body = get_json(f"/v1/neighborhoods/{neighborhood_code}/streets", params)
        items.extend(body["data"])
        cursor = body["meta"]["nextCursor"]
        if not cursor:
            return items


def cached_streets(neighborhood_code, version):
    key = f"streets:{neighborhood_code}"
    hit = _cache.get(key)
    if hit and hit[0] == version and hit[1] > time.time():
        return hit[2]
    data = all_streets(neighborhood_code)
    _cache[key] = (version, time.time() + TTL, data)
    return data


version = dataset_version()
streets = cached_streets("20239", version)

Örnekteki mahalle kodu yalnız gösterim amaçlıdır. Uygulamanızda mahalle listesi yanıtından aldığınız gerçek kodları kullanın.

API önbellekleme mimarisinde dikkat edilecekler

  • Önbelleği sunucuda tutun. API anahtarı tarayıcıya konmaz. Ön yüz kendi sunucunuza istek atar; önbellek de bu katmanda bulunur. Birden fazla sunucu çalıştırıyorsanız bellek içi Map yerine paylaşılan bir önbellek deposu kullanın. Böylece sürüm değişikliği tüm örneklere aynı anda yansır.
  • Tarayıcı önbelleğini kendi uçlarınızla yönetin. Kendi sunucunuzun döndürdüğü il ve ilçe listelerine Cache-Control başlığı ekleyebilirsiniz. Yanıta sürüm parmak izini koyarsanız ön yüz, localStorage içindeki eski listeyi sürüm değiştiğinde atabilir.
  • Eşzamanlı yenilemeyi tekilleştirin. Sürüm değiştiği anda aynı listeyi isteyen çok sayıda kullanıcı aynı API çağrısını tetikleyebilir. Devam eden isteği bir Promise olarak saklayıp diğer çağıranlara aynı sonucu vermek, gereksiz istekleri önler.
  • Doğrulama sonucunu kalıcı gerçek gibi saklamayın. valid: true yanıtı, o anki katalog sürümüne göre verilmiş bir sonuçtur. Siparişle birlikte meta.datasetVersion değerini de kaydederseniz, hangi sürüme göre doğrulandığını sonradan görebilirsiniz.

stableId ile sürüm değişikliklerine dayanıklılık

Önbelleği yenilemek listeleri günceller. Peki daha önce veritabanınıza kaydettiğiniz adreslere ne olur? Burada belirleyici olan, referans olarak hangi alanı sakladığınızdır.

Her kayıt, sürümden bağımsız bir stableId taşır. Kullanıcının seçtiği il, ilçe, mahalle, sokak ve kapıyı stableId ile saklarsanız katalog sürümü değiştiğinde kayıtlarınız boşa düşmez. Yeni önbellekteki listelerde aynı stableId değerini bulup güncel adı gösterebilirsiniz. Yeni listede bulunamayan bir stableId, ilgili adresin gözden geçirilmesi gerektiğini gösteren somut bir sinyaldir.

Dış kapılardaki id alanının durumu farklıdır. Bu alan aktif katalog sürümüne aittir ve sürümler arasında değişebilir. Bu yüzden id değerini kalıcı referans olarak saklamayın ve önbellekteki kapı listelerini sürüm değiştikten sonra kullanmayın. Doğrulama isteğinde doorId göndermeniz gerekiyorsa değeri güncel sürümün /v1/streets/{code}/buildings yanıtından alın. code alanını kaynakla eşleştirme için yanında tutabilirsiniz.

Bu ayrımı veritabanı şemasına nasıl yansıtacağınızı Adres Veritabanı Tasarımı: Metin Değil, Kalıcı Kimlik yazısında ayrıntılı olarak bulabilirsiniz.

Kısa kontrol listesi

  • İl, ilçe ve mahalle listelerini katalog sürümüne bağlı olarak önbelleğe alın.
  • Cadde/sokak ve dış kapı listelerini isteğe bağlı doldurun; dış kapılar için daha kısa bir süre kullanın.
  • Sürümü /v1/meta ile düzenli aralıklarla kontrol edin. Uygunsa datasetVersion alanından da yararlanın.
  • TTL'yi bir güvenlik ağı olarak kullanın. Asıl yenileme sinyali sürüm değişikliği olsun.
  • 429 ve 503 yanıtlarında son geçerli veriyi sunun. 401 ve 403 yanıtlarını gizlemeyin.
  • Kalıcı referans olarak stableId saklayın. Dış kapı id değerini kalıcı referans olarak saklamayın.

Sonraki adım

Uçların ve yanıt alanlarının tam listesi API dokümantasyonunda yer alıyor. Kendi önbellek katmanınızı denemek için ücretsiz kayıt olup API anahtarınızı alabilir, paketlerin kapsamını da paket karşılaştırması bölümünde inceleyebilirsiniz.