De Site / CMS API gebruiken
Authenticeer, bewerk en publiceer inhoud met API v1 op het platform of een onafhankelijk CMS.
De Site / CMS API gebruiken
API v1 verbindt externe integraties met website- en CMS-gegevens. Lees het contract van je installatie, maak een sleutel met beperkte rechten en sla een concept met versiebeveiliging op.
Dienst en installatie kiezen
Stel QOKIT_API_URL in op de oorsprong van de API-dienst (lokaal http://localhost:7777) of onafhankelijke installatie. QOKIT_PROJECT_ID is de project-ID; een export bewaart die in data/seed.json als project.id. Openbare leesacties gebruiken de project-slug.
| Installatie | Mogelijkheden |
|---|---|
| Platform | CMS-beheer, exports en platformpublicatie |
cms-managed | Lokaal CMS-beheer en websiteweergave |
cms-only | Lokaal CMS-beheer en openbare headless-leesacties; geen websiteweergave |
site-only | Statische HTML-pagina's en bestanden; geen runtime-API |
Het contract ontdekken
Elke dienst beschrijft alleen ondersteunde acties. Andere acties geven 404. API 1.0 blijft compatibel met bestaande routes zonder versie.
| Pad | Doel |
|---|---|
GET /v1/openapi.json | OpenAPI 3.1: bodies, antwoorden, rechten en voorwaarden |
GET /v1/capabilities | API-versie, installatietype en ondersteunde acties |
GET /v1/sdk/client.mjs | JavaScript-client zonder afhankelijkheden |
GET /v1/sdk/client.d.mts | Bijbehorende TypeScript-declaraties |
Een API-sleutel maken
Gebruik het accessToken van een voltooide platformaanmelding als SESSION_TOKEN. Het account moet website-instellingen mogen beheren. Voltooi vereiste authenticatie voordat je een sleutel maakt.
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}'Meld je bij een onafhankelijk CMS aan met e-mail en wachtwoord van de installatie-eigenaar, bewaar de sessie-Cookie en maak de sleutel:
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}'Bij aanmaken verschijnt token één keer. Bewaar het als servervariabele QOKIT_SITE_API_KEY; aanvragen gebruiken Bearer-tokens die beginnen met qk_site_. Standaard 90 dagen geldig, instelbaar op 1–365 dagen, maximaal 50 actieve sleutels per project. Gebruik een instellingenbeheersessie om via GET /v1/projects/{id}/api-keys te tonen en via DELETE /v1/projects/{id}/api-keys/{keyId} in te trekken.
Kies alleen benodigde rechten. Elke aanvraag controleert de huidige toegang en rechten van de maker. Verloop, intrekking en rolwijzigingen gelden voor volgende aanvragen. API-sleutels beheren geen andere sleutels.
| Scope | Doel |
|---|---|
content:read / content:write | Collecties en items lezen / bewerken |
content:publish | Expliciet publiceren en schrijfacties die items publiceren |
pages:read / pages:write | Runtime lezen / inhoud, structuur, SEO en formulieren bewerken |
media:read / media:write | Media en mappen lezen / beheren |
settings:read / settings:write | Website-instellingen lezen / bewerken |
users:read / users:write | CMS-gebruikers lezen / beheren |
leads:read / leads:write / analytics:read | Leads lezen / bijwerken en CMS-dashboard lezen |
marketing:read / marketing:write | Marketinginhoud lezen / genereren |
deployments:read / deployments:write | Platformtaken voor export en publicatie |
sync:write / updates:read / updates:write | Synchronisatie en ondertekende updates van onafhankelijke installaties |
Een concept opslaan met de SDK
Het workspace-pakket is @qokit/site-api; het staat nog niet op npm. Download voor een extern project beide clientbestanden naar sdk. Nieuwe exports bevatten ze al.
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.mtsDit voorbeeld vereist content:read en content:write. Vervang en door een ingeschakelde projecttaal. Het maakt een voorbeeldcollectie; hergebruik bij volgende runs een bestaande collectie-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);Een concept bewaren behoudt de vorige openbare snapshot van een gepubliceerd item. Na controle kan een sleutel met content:publish de opgeslagen versie expliciet publiceren. Platformpagina’s blijven concepten tot de websitepublicatie is voltooid.
await api.entries.publish(saved._id, { expectedUpdatedAt: saved.updatedAt });Lees voor herstel api.entries.revisions(id) en roep api.entries.restore(id, revisionId, { expectedUpdatedAt }) aan. Gebruik voor andere gedocumenteerde acties api.request(path, options), inclusief idempotencyKey. De client herhaalt schrijfacties nooit automatisch.
Beheerroutes
Voeg /v1/projects/{id} voor deze paden toe. OpenAPI noemt alle acties, velden en installatievereisten. DELETE archiveert collecties, items en media.
| Pad | 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 |
Platformmedia ondersteunt URL-registratie en uploadintenties; onafhankelijke uploads gebruiken fileName, contentType en contentBase64, maximaal 10 MB met controle van bestandssignaturen. Platformgebruikerswijzigingen vereisen Idempotency-Key; lokale gebruikers een wachtwoord van 12–1024 tekens. CSV, bulkbewerkingen en vertaalrelaties zijn platformuitbreidingen.
Versies, paginering en fouten
Wijzigingen, archivering en revisieherstel vereisen expectedUpdatedAt van de laatst gelezen updatedAt. Een ontbrekende versie geeft 428, een verouderde versie 409.
Lees voor structuur, SEO en formulieren GET /v1/projects/{id}/runtime en stuur content.updatedAt en siteVersion.updatedAt als baseContentUpdatedAt en baseSiteVersionUpdatedAt. Platformcontroles voor Builder-revisies en actieve bewerkingsleases blijven gelden.
Lijsten gebruiken standaard page=1&pageSize=24, met maximaal 100 items per pagina. Beheerlijsten geven items, openbare lijsten entries. Revisies en mappen geven arrays. Lees alle pagina’s bij inhoudsexport.
{"items":[],"page":1,"pageSize":24,"total":0,"totalPages":1}Antwoorden bevatten X-Request-Id en X-Qokit-Api-Version. Fouten hebben een vaste code en aanvraag-ID:
{"statusCode":409,"message":"This resource changed.","error":{"code":"CONFLICT","message":"This resource changed.","requestId":"request-id"}}Controleer bij 401 de sleutel, bij 403 rechten en toegang van de maker. Lees bij 409 opnieuw en vergelijk wijzigingen; voeg bij 428 de versie toe. Respecteer bij 429 Retry-After. Het limiet is 300 aanvragen per minuut per sleutel/adres, met extra platformlimieten voor IP en schrijven.
Onafhankelijke installatie configureren
Platformbrowserintegraties gebruiken CORS_ALLOWED_ORIGINS. Onafhankelijke browseraanvragen met sleutels vereisen exacte oorsprongen in SITE_API_ALLOWED_ORIGINS; Cookie-beheer blijft binnen dezelfde oorsprong. Openbare CMS-leesacties kunnen ook CMS_ALLOWED_ORIGINS gebruiken. Configureer CMS_PUBLIC_URL voor CMS-only-media-URL’s.
Maak een back-up van alle gegevens en uploads, inclusief privébestanden data/api-security.json en data/api-revisions.json. Wachtwoorden en sleutels blijven lokaal als hashes. Eén Node-proces schrijft per gegevensmap.
Oude exports krijgen v1 via een ondertekende runtime-update. Download daarna het actuele contract en de client via HTTP; gebundelde bestanden blijven exportsnapshots.
Voor openbare leesacties zonder inloggegevens, zie De openbare inhoud-API aanroepen.
Laatst bijgewerkt op