Skip to Content
Ontwikkelaarsdocumentatie

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.

InstallatieMogelijkheden
PlatformCMS-beheer, exports en platformpublicatie
cms-managedLokaal CMS-beheer en websiteweergave
cms-onlyLokaal CMS-beheer en openbare headless-leesacties; geen websiteweergave
site-onlyStatische 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.

PadDoel
GET /v1/openapi.jsonOpenAPI 3.1: bodies, antwoorden, rechten en voorwaarden
GET /v1/capabilitiesAPI-versie, installatietype en ondersteunde acties
GET /v1/sdk/client.mjsJavaScript-client zonder afhankelijkheden
GET /v1/sdk/client.d.mtsBijbehorende 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.

ScopeDoel
content:read / content:writeCollecties en items lezen / bewerken
content:publishExpliciet publiceren en schrijfacties die items publiceren
pages:read / pages:writeRuntime lezen / inhoud, structuur, SEO en formulieren bewerken
media:read / media:writeMedia en mappen lezen / beheren
settings:read / settings:writeWebsite-instellingen lezen / bewerken
users:read / users:writeCMS-gebruikers lezen / beheren
leads:read / leads:write / analytics:readLeads lezen / bijwerken en CMS-dashboard lezen
marketing:read / marketing:writeMarketinginhoud lezen / genereren
deployments:read / deployments:writePlatformtaken voor export en publicatie
sync:write / updates:read / updates:writeSynchronisatie 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.mts

Dit 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.

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

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.

Was deze gids nuttig?

Laatst bijgewerkt op

Op deze pagina