jekcms REST API: Geliştiriciler İçin Pratik Rehber

jekcms, /api/v1 altında tek ve kararlı bir REST API sunar. Bu rehber bir entegrasyonun gerçekten dokunduğu parçaları anlatır: kimlik doğrulama, uç nokta haritası, yayınlama davranışı ve hız limitleri — güncel sürümde gerçekte çalıştıkları hâliyle.

Kimlik Doğrulama

API, admin panelinden oluşturup iptal edebileceğiniz statik token'lar kullanır. Token'ı ister X-API-Key başlığıyla ister standart bearer token olarak gönderin — ikisi de kabul edilir:

curl https://siteniz.com/api/v1/posts \
 -H "Authorization: Bearer TOKENINIZ"

# eşdeğeri:
curl https://siteniz.com/api/v1/posts \
 -H "X-API-Key: TOKENINIZ"

Token'lar sunucuda SHA-256 hash olarak saklanır, isteğe bağlı son kullanma tarihi taşıyabilir ve tek tek devre dışı bırakılabilir. Refresh-token karmaşası yoktur: yeni token oluşturup entegrasyonu geçirin, eskisini kapatın.

Yanıt Zarfı

Her yanıt aynı sarmalayıcıyı kullanır. Başarı:

{"success": true, "data": { ... }}

Hatalar HTTP kodu ve mesaj taşır:

{"success": false, "error": {"code": 401, "message": "Unauthorized"}}

Uç Nokta Haritası

• /api/v1/posts — listele, oku, oluştur, güncelle, sil; ayrıca publish ve schedule eylemleri ile revisions okuyucu
• /api/v1/media — dosya yükleme ve yönetim
• /api/v1/categories, /api/v1/tags — taksonomi
• /api/v1/comments — moderasyon
• /api/v1/users — yazar yönetimi
• /api/v1/settings — site ayarları
• /api/v1/webhooks — giden webhook yönetimi
• /api/v1/stats, /api/v1/trends — analitik veriler
• /api/v1/search, /api/v1/sitemap, /api/v1/health — yardımcılar

Yazma Yetkisi Role Duyarlıdır

Token, ait olduğu kullanıcının rolünü devralır. İçeriği değiştirmek için kimlik doğrulama tek başına yetmez: yazar seviyesindeki bir token yalnızca kendi yazılarını değiştirebilir, yayınlama yetkisi düzenleme yetkisinden ayrı denetlenir. Entegrasyonlara işi görebilen en düşük yetkili kullanıcıyı verin.

Yayınlama, Diğer Her Kanalla Aynı Kapıdan Geçer

status: "published" ile yazı oluşturmak ya da publish eylemini çağırmak hiçbir şeyi atlatmaz: istek, diğer tüm kanallarla aynı yayın politikasından geçer. Kaynak api olarak kaydedilir, yayın modu saklanır ve içerik kalite kapısı açıksa ve taslak kapıyı geçemezse yazı taslakta kalır — yanıt nedenini söyler.

Yazı yanıtları ayrıca review_valid alanı içerir: insan onayı mevcut içerik için hâlâ geçerliyse true, içerik onaydan sonra değiştiyse false, yazı hiç insan onayından geçmediyse null. Editoryal tarihler de yanıtın parçasıdır; entegrasyonlar yanlışlıkla sahte güncellik üretemez.

Publish ve Schedule Eylemleri

# Mevcut taslağı yayınla
curl -X POST https://siteniz.com/api/v1/posts/42/publish \
 -H "Authorization: Bearer TOKENINIZ"

# Ya da zamanla
curl -X POST https://siteniz.com/api/v1/posts/42/schedule \
 -H "Content-Type: application/json" \
 -H "Authorization: Bearer TOKENINIZ" \
 -d '{"scheduled_at": "2026-08-01 09:00:00"}'

Zamanlama yalnızca etiketler; kalite kapısı yazı gerçekten yayına döndüğü anda çalışır. Bu dönüş sistem cron'u olmadan da işler — yerleşik pseudo-cron normal site trafiğinde tetikler.

Hız Limiti

API, IP başına ortak bir hız limiti uygular (varsayılan saatte 100 istek, API_RATE_LIMIT ile yapılandırılabilir). Aşınca HTTP 429 ve "Rate limit exceeded" döner. Yazma isteklerini gruplandırın ve 429'da geri çekilin.

Pratik Öneriler

• Tek doğruluk kaynağı success: false + HTTP kodudur — mesaj metnini parse etmeyin.
• Yıkıcı güncellemelerden önce revisions ucunu kullanın; her içerik değişikliği sunucu tarafında anlık görüntülenir.
• İçeriğe bir insanın bakması gerekiyorsa doğrudan status: "published" yerine taslak-sonra-yayınla akışını tercih edin.