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.
| Bereitstellung | Funktionen |
|---|---|
| Plattform | CMS-Verwaltung, Exporte und Plattformveröffentlichung |
cms-managed | Lokale CMS-Verwaltung und Website-Darstellung |
cms-only | Lokale CMS-Verwaltung und öffentliche Headless-Lesezugriffe; keine Website-Darstellung |
site-only | Statische 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.
| Pfad | Zweck |
|---|---|
GET /v1/openapi.json | OpenAPI 3.1: Request-Bodies, Antworten, Rechte und Voraussetzungen |
GET /v1/capabilities | API-Version, Bereitstellungstyp und unterstützte Operationen |
GET /v1/sdk/client.mjs | JavaScript-Client ohne Abhängigkeiten |
GET /v1/sdk/client.d.mts | Passende 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.
| Scope | Zweck |
|---|---|
content:read / content:write | Sammlungen und Einträge lesen / bearbeiten |
content:publish | Explizite Veröffentlichung und veröffentlichende Schreibzugriffe |
pages:read / pages:write | Runtime lesen / Seiteninhalt, Struktur, SEO und Formulare bearbeiten |
media:read / media:write | Medien und Ordner lesen / verwalten |
settings:read / settings:write | Website-Einstellungen lesen / bearbeiten |
users:read / users:write | CMS-Benutzer lesen / verwalten |
leads:read / leads:write / analytics:read | Leads lesen / aktualisieren und CMS-Dashboard lesen |
marketing:read / marketing:write | Marketinginhalte lesen / generieren |
deployments:read / deployments:write | Export- und Veröffentlichungsjobs der Plattform |
sync:write / updates:read / updates:write | Synchronisierung 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.mtsDas 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.
| Pfad | Methode |
|---|---|
/cms/collections | GET, POST |
/cms/collections/{collectionId} | PUT, DELETE |
/cms/collections/{collectionId}/entries | GET, POST |
/cms/entries/{entryId} | GET, PUT, DELETE |
/cms/entries/{entryId}/publish | POST |
/cms/entries/{entryId}/revisions | GET |
/cms/entries/{entryId}/revisions/{revisionId}/restore | POST |
/cms/media, /cms/media/folders | GET, 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/forms | POST, DELETE, PUT, PUT |
/cms/settings | GET, 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.
Zuletzt aktualisiert