Skip to Content
Entwicklerdokumentation

Site- / CMS-API verwenden

Inhalte auf der Plattform oder in einem unabhängigen CMS über API v1 authentifizieren, bearbeiten und veröffentlichen.

Site- / CMS-API verwenden

API v1 verbindet externe Integrationen mit Website- und CMS-Daten. Lesen Sie zuerst den Vertrag Ihrer Bereitstellung, erstellen Sie einen Schlüssel mit begrenzten Rechten und speichern Sie einen Entwurf mit Versionsschutz.

Dienst und Bereitstellung auswählen

Setzen Sie QOKIT_API_URL auf den Ursprung des API-Dienstes (lokal http://localhost:7777) oder der unabhängigen Installation. QOKIT_PROJECT_ID bezeichnet die Projekt-ID; Exporte speichern sie in data/seed.json als project.id. Öffentliche Lesezugriffe verwenden den Projekt-slug.

BereitstellungFunktionen
PlattformCMS-Verwaltung, Exporte und Plattformveröffentlichung
cms-managedLokale CMS-Verwaltung und Website-Darstellung
cms-onlyLokale CMS-Verwaltung und öffentliche Headless-Lesezugriffe; keine Website-Darstellung
site-onlyStatische HTML-Seiten und Ressourcen; keine Laufzeit-API

Vertrag abrufen

Jeder Dienst beschreibt nur unterstützte Operationen. Nicht unterstützte Aufrufe liefern 404. API 1.0 bleibt mit bestehenden unversionierten Routen kompatibel.

PfadZweck
GET /v1/openapi.jsonOpenAPI 3.1: Request-Bodies, Antworten, Rechte und Voraussetzungen
GET /v1/capabilitiesAPI-Version, Bereitstellungstyp und unterstützte Operationen
GET /v1/sdk/client.mjsJavaScript-Client ohne Abhängigkeiten
GET /v1/sdk/client.d.mtsPassende TypeScript-Deklarationen

API-Schlüssel erstellen

Verwenden Sie den accessToken einer abgeschlossenen Plattformanmeldung als SESSION_TOKEN. Das Konto benötigt das Recht zur Verwaltung der Website-Einstellungen. Schließen Sie erforderliche Authentifizierungsschritte vor der Schlüsselerstellung ab.

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}'

Melden Sie sich beim unabhängigen CMS mit E-Mail und Passwort des Bereitstellungseigentümers an, speichern Sie das Sitzungscookie und erstellen Sie den Schlüssel:

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}'

Nur die Erstellung gibt token zurück. Speichern Sie ihn als Serverumgebungsvariable QOKIT_SITE_API_KEY; Aufrufe verwenden Bearer-Tokens mit dem Präfix qk_site_. Standardgültigkeit: 90 Tage, einstellbar auf 1–365 Tage, maximal 50 aktive Schlüssel pro Projekt. Mit einer Einstellung-Administrator-Sitzung über GET /v1/projects/{id}/api-keys auflisten und über DELETE /v1/projects/{id}/api-keys/{keyId} widerrufen.

Wählen Sie nur benötigte Rechte. Zugriff und aktuelle Berechtigungen des Erstellers werden bei jedem Aufruf geprüft. Ablauf, Widerruf und Rollenänderungen wirken auf Folgeaufrufe. API-Schlüssel können keine anderen Schlüssel verwalten.

ScopeZweck
content:read / content:writeSammlungen und Einträge lesen / bearbeiten
content:publishExplizite Veröffentlichung und veröffentlichende Schreibzugriffe
pages:read / pages:writeRuntime lesen / Seiteninhalt, Struktur, SEO und Formulare bearbeiten
media:read / media:writeMedien und Ordner lesen / verwalten
settings:read / settings:writeWebsite-Einstellungen lesen / bearbeiten
users:read / users:writeCMS-Benutzer lesen / verwalten
leads:read / leads:write / analytics:readLeads lesen / aktualisieren und CMS-Dashboard lesen
marketing:read / marketing:writeMarketinginhalte lesen / generieren
deployments:read / deployments:writeExport- und Veröffentlichungsjobs der Plattform
sync:write / updates:read / updates:writeSynchronisierung und signierte Updates unabhängiger Installationen

Entwurf mit dem SDK speichern

Das Workspace-Paket heißt @qokit/site-api; es wurde noch nicht auf npm veröffentlicht. Laden Sie für externe Projekte beide Clientdateien nach sdk. Neue Exporte enthalten sie bereits.

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

Das Beispiel benötigt content:read und content:write. Ersetzen Sie en durch eine aktivierte Projektsprache. Es erstellt eine neue Beispielsammlung; verwenden Sie bei weiteren Ausführungen eine vorhandene Sammlungs-ID.

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);

Ein gespeicherter Entwurf erhält den bisherigen öffentlichen Snapshot eines veröffentlichten Eintrags. Nach Prüfung kann ein Schlüssel mit content:publish die gespeicherte Version explizit veröffentlichen. Plattformseiten bleiben bis zum Abschluss der Website-Veröffentlichung Entwürfe.

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

Zur Wiederherstellung lesen Sie api.entries.revisions(id) und rufen api.entries.restore(id, revisionId, { expectedUpdatedAt }) auf. Andere dokumentierte Operationen verwenden api.request(path, options), einschließlich idempotencyKey. Der Client wiederholt Schreibzugriffe nicht automatisch.

Verwaltungsrouten

Stellen Sie diesen Pfaden /v1/projects/{id} voran. OpenAPI enthält alle Operationen, Felder und dienstspezifischen Anforderungen. DELETE archiviert Sammlungen, Einträge und Medien.

PfadMethode
/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

Plattformmedien unterstützen URL-Registrierung und Upload-Vorgänge; unabhängige Uploads verwenden fileName, contentType und contentBase64, maximal 10 MB und mit Signaturprüfung. Plattform-Benutzeränderungen benötigen Idempotency-Key; lokale Benutzer ein Passwort mit 12–1024 Zeichen. CSV, Stapeländerungen und Übersetzungsverknüpfungen sind Plattform-Erweiterungen.

Versionen, Seitennavigation und Fehler

Änderungen, Archivierung und Revisionswiederherstellung benötigen expectedUpdatedAt aus dem zuletzt gelesenen updatedAt. Fehlende Versionen liefern 428, veraltete Versionen 409.

Für Struktur, SEO und Formulare lesen Sie GET /v1/projects/{id}/runtime und senden content.updatedAt und siteVersion.updatedAt als baseContentUpdatedAt und baseSiteVersionUpdatedAt. Builder-Revisionsprüfungen und aktive Bearbeitungssperren bleiben auf der Plattform wirksam.

Listen verwenden standardmäßig page=1&pageSize=24 mit maximal 100 Elementen pro Seite. Verwaltungslisten liefern items, öffentliche Listen entries. Revisionen und Ordner liefern Arrays. Lesen Sie zum Exportieren alle Seiten.

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

Antworten enthalten X-Request-Id und X-Qokit-Api-Version. Fehler enthalten einen stabilen Code und eine Request-ID:

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

Bei 401 Schlüsselgültigkeit prüfen, bei 403 Rechte und Erstellerzugriff. Bei 409 erneut lesen und Änderungen vergleichen, bei 428 die Version ergänzen. Bei 429 Retry-After beachten. Das Limit beträgt 300 Anfragen pro Minute je Schlüssel/Adresse, zusätzlich zu Plattform-IP- und Schreiblimits.

Unabhängige Installation konfigurieren

Die Plattform verwendet CORS_ALLOWED_ORIGINS für Browserintegrationen. Unabhängige Browseraufrufe mit Schlüsseln benötigen genaue Ursprünge in SITE_API_ALLOWED_ORIGINS; Cookie-Verwaltung bleibt ursprungsgleich. Öffentliche CMS-Lesezugriffe erlauben auch CMS_ALLOWED_ORIGINS. Für CMS-only-Medien-URLs konfigurieren Sie CMS_PUBLIC_URL.

Sichern Sie Datenverzeichnis und Uploads vollständig, einschließlich der privaten Dateien data/api-security.json und data/api-revisions.json. Passwörter und Schlüssel bleiben lokal als Hashes. Pro Datenverzeichnis schreibt ein einzelner Node-Prozess.

Ältere Exporte erhalten v1 durch ein signiertes Runtime-Update. Laden Sie danach aktuellen Vertrag und Client über HTTP; enthaltene Dateien bleiben Snapshots des Exportzeitpunkts.

Für öffentliche Lesezugriffe ohne Zugangsdaten siehe Öffentliche Content-API aufrufen.

War diese Anleitung hilfreich?

Zuletzt aktualisiert

Auf dieser Seite