Taşıyıcı token kimlik doğrulaması, 30 günlük yenileme tokenlarıyla eşleştirilmiş kısa ömürlü erişim tokenları (15 dakika TTL) kullanıyor. İlk token çiftini POST /api/v2/auth/token ile API kimlik bilgilerinizi istek gövdesinde geçirerek alın.

Sonraki isteklere erişim tokenını Authorization: Bearer {token} olarak ekleyin. Bir erişim tokenı süresi dolduğunda POST /api/v2/auth/refresh'te yenileme tokenını yeni bir çiftle değiştirin. Erişim tokenını istek döngüsünün ötesinde saklamayın; yalnızca yenileme tokenını güvenli biçimde depolayın.

İmleç Sayfalandırması Kayma Sorununu Çözüyor

İmleç tabanlı sayfalandırma ?page=N kalıbının yerini alıyor. Ek sonuçları olan her yanıt, meta nesnesinde bir next_cursor değeri içeriyor. Bir sonraki istekte ?cursor={değer} olarak geçirin. Bu yaklaşım "sayfa kayması" sorununu önlüyor: ofset sayfalandırmayla, bir istemci sonuçlar arasında gezinirken yeni bir gönderi eklemek istemcinin gönderileri atlayıp jekcms.alfadizayn.com/tr/blog/jekcms-v1-4-0-cok-dilli-motor-bastan-yeniden-yazildi" class="auto-link" target="_blank" rel="noopener">yeniden okumasına gerekçe oluyor. İmleç sayfalandırması ekleme ya da silmeden bağımsız olarak kararlı kalıyor.

Birleşik Yanıt Zarfı

Birleşik yanıt zarfı {"success": true, "data": {...}, "meta": {...}, "errors": []}. V1'de her uç nokta kendi yapısını döndürüyordu — bazıları ana kaynağı kaynak türüyle eşleşen bir anahtar altında iç içe geçiriyordu ({"post": {...}}), bazıları kaynağı doğrudan kökte döndürüyordu. v2 tutarlı: kaynak her zaman data altında, sayfalandırma meta verisi her zaman meta altında ve hatalar her zaman errors dizisinde.

Taşıma Stratejisi: Uç Nokta Başına

V1 uç noktaları aktif kalmaya devam ediyor ve v1.6.0'a kadar güvenlik yamalarını alacak. Entegrasyonunuz büyük sonuç kümelerini dışa aktarmak gibi amaçlarla ofset sayfalandırmasını yoğun kullanıyorsa, imlece geçiş tek sayfayı aşan sonuç kümelerini nasıl yönettiğinizi yeniden düşünmeyi gerektiriyor. Durumu değiştiren POST ve PATCH uç noktalarına geçmeden önce salt okunur GET uç noktalarından başlayarak birer birer taşımanızı öneriyoruz.

Kimlik Dogrulama: Kod Ornekleri

Erisim tokeni alma ve sonraki isteklerde kullanma sureci uc adimdan olusur: ilk token ciftini API kimlik bilgileriyle alin, erisim tokenini Authorization: Bearer basligi olarak sonraki isteklere ekleyin ve suresi doldugunda yenileme tokeniyla yeni cift alin. Yenileme tokenlarini sifrelenmis veritabani sutununda veya gizli anahtar yoneticisinde saklayin. Erisim veya yenileme tokenlarini asla uygulama gunluklerine kaydetmeyin.

Token Saklama En Iyi Uygulamalari

Sunucudan sunucuya entegrasyonlarda otomatik token rotasyonu uygulayin: suresi dolduktan sonra degil, dolmadan 60 saniye once yeni token cifti isteyin. Bu, rotasyon penceresi sirasinda basarisiz istekleri onler.

Imlec Sayfalandirmasi: Uygulama Detaylari

Imlec degeri siralama anahtarini ve kayit kimligini iceren opak, base64 kodlu bir dizedir. Imlec degerlerini cozmeye, olusturmaya veya degistirmeye calismayin. 100.000 gonderi iceren bir tabloda v1 istegi ?page=500&per_page=20 yaklasik 1.200ms surer cunku MySQL 20 dondrmeden once 10.000 satiri tarar. Esdeger imlec istegi, sonuc kumesindeki konumdan bagimsiz olarak tutarli 15-25ms surer.

v2'de Hata Yonetimi

v2 hata formati yapilandirilmis hata bilgisi saglar. Entegrasyonunuzda islemeniz gereken temel hata kodlari:

  • AUTH_EXPIRED (HTTP 401): erisim tokeni suresi dolmus. Yenileyin ve tekrar deneyin.
  • AUTH_INVALID (HTTP 401): token bozuk veya iptal edilmis. Sifirdan kimlik dogrulamasi yapin.
  • RATE_LIMITED (HTTP 429): cok fazla istek. Beklenecek saniyeler icin Retry-After basligini kontrol edin.
  • VALIDATION_FAILED (HTTP 422): istek govdesi dogrulamayi gecemedi. Alan bazli mesajlar icin errors dizisini kontrol edin.
  • NOT_FOUND (HTTP 404): kaynak mevcut degil veya mevcut token kapamiyla erisilebilir degil.

v1 - v2 Uc Nokta Eslestirmesi

Entegrasyon uc noktalarinizi guncellerken bu referansi kullanin:

  • GET /api/v1/posts yerine GET /api/v2/posts
  • POST /api/v1/posts/create yerine POST /api/v2/posts (RESTful)
  • POST /api/v1/posts/update/{id} yerine PATCH /api/v2/posts/{id}
  • POST /api/v1/posts/delete/{id} yerine DELETE /api/v2/posts/{id}
  • GET /api/v1/media/list yerine GET /api/v2/media

v2 uc noktalari tutarli bicimde RESTful kurallarina uyar: kaynak koleksiyonlari cogul isimler kullanir, bireysel kaynaklar koleksiyon adi arti kimlik kullanir ve HTTP yontemleri eylemi belirtir.

Hiz Sinirlandirma ve Kisitlama

API v2, token basina hiz sinirlandirmasi sunar. Varsayilan sinirlar standart tokenlar icin dakikada 60 istek ve yonetici tokenlari icin dakikada 300 istektir. Hiz siniri basliklari her yanita dahil edilir:

  • X-RateLimit-Limit: pencere basina izin verilen maksimum istek
  • X-RateLimit-Remaining: mevcut pencerede kalan istekler
  • X-RateLimit-Reset: pencerenin sifirlanacagi Unix zaman damgasi

Sinira ulastiginizda API, Retry-After basligiyla HTTP 429 dondurur. Harici bir CMS'den 10.000 gonderi iceri aktarma gibi toplu islemler icin, istek basina 100 kayit kabul eden /api/v2/bulk/posts uc noktasini kullanin. Bu, 10.000 isteklik bir tasimayi 100 istege dusurup 2 dakikanin altinda tamamlar.

Tasima Sirasinda Geriye Donuk Uyumluluk

v1 ve v2 uc noktalari bir sureligine paralel calisacagindan, tasima doneminde her iki API surumunu ayni anda destekleyen bir istemci katmani olusturmaniz onerilir.

API istemcinizde surum sabitini merkezi bir yapilandirma dosyasindan okuyun; boylece geçis tamamlandiginda tek bir degisiklikle tum istekleri v2'ye yonlendirebilirsiniz.

Eger n8n veya benzeri otomasyon araclariyla JekCMS API'sine baglaniyorsaniz, her workflow'daki HTTP istek dugumlerini ayri ayri guncellemeniz gerekecektir. Bu surecte eski v1 istek formatini yedek olarak saklayin; beklenmedik bir sorunla karsilasirsaniz hizla geri donebilirsiniz. JekCMS, v1 kullanimdan kaldirilmadan en az uc ay once admin panelinde uyari bildirimi gosterecektir.

Webhook Entegrasyonlarinda API Surumu Yonetimi

Webhook kullanan entegrasyonlarda API surumunu yonetmek ozellikle onemlidir. JekCMS'in gonderdigi webhook payload'lari v2 ile birlikte yeni alanlar icermeye baslar; ancak mevcut alanlarin yapisi degismez. Webhook alicisi olarak calisan harici sistemlerinizi, tanimadiklari alanlari yok sayacak sekilde yapilandirin; bu sayede v2'ye gecis sirasinda webhook isleyicileriniz kirilmaz.

Tasima tamamlandiginda webhook yapilandirma ekranindan endpoint URL'sini v2 formatina guncellemeniz yeterlidir.

JekCMS admin panelindeki webhook test aracini kullanarak degisiklik yapmadan once yeni payload yapisini inceleyebilir ve alici tarafin dogru calistigini dogrulayabilirsiniz. Boylece hem otomasyon akislariniz kesintisiz calisir hem de v2'nin sundugun yeni veri alanlarindan yararlanabilirsiniz. Toplu tasima planliyorsaniz once bir staging ortaminda butun entegrasyonlari test etmeniz siddatle tavsiye edilir.