Skip to Content
Geliştirici dokümantasyonu

Site / CMS API kullanımı

Platformda veya bağımsız CMS üzerinde API v1 ile kimlik doğrulayın, içerik düzenleyin ve yayımlayın.

Site / CMS API kullanımı

API v1, dış entegrasyonları site ve CMS verilerine bağlar. Dağıtım sözleşmesini inceleyin, sınırlı yetkili bir anahtar oluşturun ve sürüm korumasıyla taslak kaydedin.

Hizmet ve dağıtım seçimi

QOKIT_API_URL değerini API hizmetinin (yerelde http://localhost:7777) veya bağımsız kurulumun origin adresine ayarlayın. QOKIT_PROJECT_ID proje kimliğidir; dışa aktarım bunu data/seed.json içinde project.id olarak saklar. Açık okumalar proje slug değerini kullanır.

DağıtımYetenekler
PlatformCMS yönetimi, dışa aktarım ve platform yayını
cms-managedYerel CMS yönetimi ve site oluşturma
cms-onlyYerel CMS yönetimi ve açık headless okumalar; site oluşturma yok
site-onlyStatik HTML sayfaları ve varlıklar; çalışma zamanı API'si yok

Sözleşmeyi keşfetme

Her hizmet yalnızca desteklediği işlemleri açıklar. Diğer işlemler 404 döndürür. API 1.0, mevcut sürümsüz yolların uyumluluğunu korur.

YolAmaç
GET /v1/openapi.jsonOpenAPI 3.1: istek gövdeleri, yanıtlar, izinler ve ön koşullar
GET /v1/capabilitiesAPI sürümü, dağıtım türü ve desteklenen işlemler
GET /v1/sdk/client.mjsBağımlılıksız JavaScript istemcisi
GET /v1/sdk/client.d.mtsEşleşen TypeScript bildirimleri

API anahtarı oluşturma

Tamamlanmış platform girişinin accessToken değerini SESSION_TOKEN olarak kullanın. Hesap site ayarlarını yönetebilmelidir. Anahtar oluşturmadan önce gerekli kimlik doğrulamayı tamamlayın.

curl --fail-with-body "$QOKIT_API_URL/v1/projects/$QOKIT_PROJECT_ID/api-keys" \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Server integration","scopes":["content:read","content:write"],"expiresInDays":90}'

Bağımsız CMS için dağıtım sahibinin e-postası ve parolasıyla giriş yapın, oturum Cookie bilgisini saklayın ve anahtarı oluşturun:

curl --fail-with-body -c cookies.txt "$QOKIT_API_URL/api/auth/login" \
  -H 'Content-Type: application/json' \
  -d '{"email":"owner@example.com","password":"your-deployment-password"}'
curl --fail-with-body -b cookies.txt "$QOKIT_API_URL/v1/projects/$QOKIT_PROJECT_ID/api-keys" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Server integration","scopes":["content:read","content:write"],"expiresInDays":90}'

Oluşturma token değerini yalnızca bir kez döndürür. Sunucu ortam değişkeni QOKIT_SITE_API_KEY içinde saklayın; istekler qk_site_ ile başlayan Bearer token kullanır. Varsayılan süre 90 gün, ayarlanabilir süre 1–365 gün ve proje başına en fazla 50 etkin anahtardır. Ayar yönetim oturumuyla GET /v1/projects/{id}/api-keys üzerinden listeleyin, DELETE /v1/projects/{id}/api-keys/{keyId} üzerinden iptal edin.

Yalnızca gerekli yetkileri seçin. Oluşturan kişinin güncel erişimi ve izinleri her istekte denetlenir. Süre sonu, iptal ve rol değişiklikleri sonraki isteklerde geçerlidir. API anahtarları diğer anahtarları yönetemez.

ScopeAmaç
content:read / content:writeKoleksiyon ve kayıtları okuma / düzenleme
content:publishAçık yayınlama ve kayıt yayımlayan yazmalar
pages:read / pages:writeRuntime okuma / içerik, yapı, SEO ve formları düzenleme
media:read / media:writeMedya ve klasörleri okuma / yönetme
settings:read / settings:writeSite ayarlarını okuma / düzenleme
users:read / users:writeCMS kullanıcılarını okuma / yönetme
leads:read / leads:write / analytics:readPotansiyel müşterileri okuma / güncelleme ve CMS panelini okuma
marketing:read / marketing:writePazarlama içeriği okuma / oluşturma
deployments:read / deployments:writePlatform dışa aktarım ve yayın işleri
sync:write / updates:read / updates:writeBağımsız kurulum senkronizasyonu ve imzalı güncellemeler

SDK ile taslak kaydetme

Workspace paketi @qokit/site-api henüz npm üzerinde yayımlanmadı. Dış projeler için iki istemci dosyasını sdk içine indirin. Yeni dışa aktarımlar bunları içerir.

mkdir -p sdk
curl --fail-with-body "$QOKIT_API_URL/v1/sdk/client.mjs" -o sdk/client.mjs
curl --fail-with-body "$QOKIT_API_URL/v1/sdk/client.d.mts" -o sdk/client.d.mts

Örnek content:read ve content:write ister. en yerine etkin proje dilini yazın. Yeni örnek koleksiyon oluşturur; sonraki çalıştırmalarda mevcut koleksiyon kimliğini kullanın.

import { createSiteApiClient } from './sdk/client.mjs';

const api = createSiteApiClient({
  baseUrl: process.env.QOKIT_API_URL,
  projectId: process.env.QOKIT_PROJECT_ID,
  token: process.env.QOKIT_SITE_API_KEY
});

const collection = await api.collections.create({
  key: 'integration_example', name: 'Integration example', kind: 'generic', fields: []
});
const draft = await api.entries.create(collection._id, {
  title: 'Integration draft', locale: 'en', status: 'draft', fields: {}
});
const saved = await api.entries.update(draft._id, { title: 'Reviewed copy' }, {
  expectedUpdatedAt: draft.updatedAt
});
console.log(saved._id, saved.updatedAt);

Taslak kaydetmek, yayımlanmış kaydın önceki açık görüntüsünü korur. İncelemeden sonra content:publish yetkili anahtar kaydedilmiş sürümü açıkça yayımlayabilir. Platform sayfaları site yayın süreci bitene kadar taslak kalır.

await api.entries.publish(saved._id, { expectedUpdatedAt: saved.updatedAt });

Kurtarma için api.entries.revisions(id) okuyun ve api.entries.restore(id, revisionId, { expectedUpdatedAt }) çağırın. Diğer işlemler api.request(path, options) ve idempotencyKey kullanabilir. İstemci yazmaları otomatik tekrar etmez.

Yönetim yolları

Bu yollara /v1/projects/{id} öneki ekleyin. OpenAPI tüm işlemleri, alanları ve dağıtım koşullarını açıklar. DELETE koleksiyon, kayıt ve medyayı arşivler.

YolYöntem
/cms/collectionsGET, POST
/cms/collections/{collectionId}PUT, DELETE
/cms/collections/{collectionId}/entriesGET, POST
/cms/entries/{entryId}GET, PUT, DELETE
/cms/entries/{entryId}/publishPOST
/cms/entries/{entryId}/revisionsGET
/cms/entries/{entryId}/revisions/{revisionId}/restorePOST
/cms/media, /cms/media/foldersGET, POST
/cms/media/{assetId}, /cms/media/folders/{folderId}PUT, DELETE
/runtime, /content/{locale}GET; PUT /content/{locale}
/site/pages, /site/pages/{pageId}, /site/pages/{pageId}/seo, /site/formsPOST, DELETE, PUT, PUT
/cms/settingsGET, PUT
/cms/users, /cms/users/{memberId}GET / POST, PUT / DELETE
/leads, /leads/{leadId}GET, PUT

Platform medyası URL kaydı ve yükleme hazırlığı destekler; bağımsız yüklemeler fileName, contentType, contentBase64 kullanır, 10 MB sınırı ve dosya imzası doğrulaması vardır. Platform kullanıcı değişiklikleri Idempotency-Key, yerel kullanıcılar 12–1024 karakter parola ister. CSV, toplu yazmalar ve çeviri bağlantıları platform eklentileridir.

Sürümler, sayfalama ve hatalar

Güncelleme, arşivleme ve revizyon kurtarma için expectedUpdatedAt alanını son okunan updatedAt değeriyle doldurun. Eksik sürüm 428, eski sürüm 409 döndürür.

Yapı, SEO ve formlar için GET /v1/projects/{id}/runtime okuyun; content.updatedAt ve siteVersion.updatedAt değerlerini baseContentUpdatedAt ve baseSiteVersionUpdatedAt olarak gönderin. Platformda Builder revizyon ve etkin düzenleme kiralaması denetimleri sürer.

Listeler varsayılan page=1&pageSize=24 kullanır, sayfa başına en fazla 100 öğedir. Yönetim listeleri items, açık listeler entries döndürür. Revizyon ve klasörler dizidir. Dışa aktarım için bütün sayfaları okuyun.

{"items":[],"page":1,"pageSize":24,"total":0,"totalPages":1}

Yanıtlar X-Request-Id ve X-Qokit-Api-Version içerir. Hatalar sabit kod ve istek kimliği taşır:

{"statusCode":409,"message":"This resource changed.","error":{"code":"CONFLICT","message":"This resource changed.","requestId":"request-id"}}

401 için anahtarı, 403 için yetkileri ve oluşturan kişinin erişimini kontrol edin. 409 için tekrar okuyup değişiklikleri karşılaştırın; 428 için sürümü ekleyin. 429 için Retry-After izleyin. Sınır anahtar/adres başına dakikada 300 istektir; platformun ek IP ve yazma sınırları vardır.

Bağımsız kurulum yapılandırması

Platform tarayıcı entegrasyonları CORS_ALLOWED_ORIGINS kullanır. Bağımsız anahtarlı tarayıcı çağrıları için SITE_API_ALLOWED_ORIGINS içinde tam origin adresleri gerekir; Cookie yönetimi aynı origin içinde kalır. Açık CMS okumaları CMS_ALLOWED_ORIGINS de kullanabilir. CMS-only medya adresleri için CMS_PUBLIC_URL ayarlayın.

Özel data/api-security.json ve data/api-revisions.json dahil tüm veri dizinini ve yüklemeleri yedekleyin. Parola ve anahtarlar yerelde hash olarak tutulur. Her veri dizinine yalnızca bir Node süreci yazar.

Eski dışa aktarımlar imzalı runtime güncellemesiyle v1 alır. Yükselttikten sonra güncel sözleşme ve istemciyi HTTP üzerinden indirin; paket dosyaları dışa aktarım anının görüntüsüdür.

Kimlik bilgisi gerektirmeyen açık okumalar için bkz. Açık içerik API çağrıları.

Bu kılavuz yararlı oldu mu?

Son güncelleme tarihi:

Bu Sayfada