Usare l’API di siti / CMS
Autentica, modifica e pubblica contenuti con API v1 sulla piattaforma o in un CMS indipendente.
Usare l’API di siti / CMS
API v1 collega integrazioni esterne ai dati di siti e CMS. Consulta il contratto della distribuzione, crea una chiave con permessi limitati e salva una bozza con protezione della versione.
Scegliere servizio e distribuzione
Imposta QOKIT_API_URL sull’origine del servizio API (in locale http://localhost:7777) o dell’installazione indipendente. QOKIT_PROJECT_ID è l’ID del progetto; l’esportazione lo salva in data/seed.json come project.id. Le letture pubbliche usano lo slug del progetto.
| Distribuzione | Funzioni |
|---|---|
| Piattaforma | Gestione CMS, esportazioni e pubblicazione sulla piattaforma |
cms-managed | Gestione CMS locale e rendering del sito |
cms-only | Gestione CMS locale e letture pubbliche headless; nessun rendering del sito |
site-only | Pagine HTML e risorse statiche; nessuna API runtime |
Consultare il contratto
Ogni servizio espone solo operazioni supportate. Le altre restituiscono 404. API 1.0 mantiene compatibilità con le rotte esistenti senza versione.
| Percorso | Scopo |
|---|---|
GET /v1/openapi.json | OpenAPI 3.1: corpi, risposte, permessi e precondizioni |
GET /v1/capabilities | Versione API, tipo di distribuzione e operazioni disponibili |
GET /v1/sdk/client.mjs | Client JavaScript senza dipendenze |
GET /v1/sdk/client.d.mts | Dichiarazioni TypeScript corrispondenti |
Creare una chiave API
Usa l’accessToken di un accesso completato alla piattaforma come SESSION_TOKEN. L’account deve poter gestire le impostazioni del sito. Completa l’autenticazione richiesta prima di emettere la chiave.
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}'Nel CMS indipendente, accedi con e-mail e password del proprietario della distribuzione, salva il Cookie di sessione e crea la chiave:
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}'La creazione restituisce token una sola volta. Salvalo nella variabile server QOKIT_SITE_API_KEY; le richieste usano token Bearer con prefisso qk_site_. Durata predefinita: 90 giorni, configurabile da 1 a 365, fino a 50 chiavi attive per progetto. Con una sessione autorizzata alle impostazioni, elenca tramite GET /v1/projects/{id}/api-keys e revoca tramite DELETE /v1/projects/{id}/api-keys/{keyId}.
Scegli solo i permessi necessari. Accesso e permessi del creatore vengono verificati a ogni richiesta. Scadenza, revoca e modifiche di ruolo valgono dalle richieste successive. Le chiavi API non gestiscono altre chiavi.
| Scope | Scopo |
|---|---|
content:read / content:write | Leggere / modificare raccolte e voci |
content:publish | Pubblicazione esplicita e scritture che pubblicano voci |
pages:read / pages:write | Leggere runtime / modificare contenuti, struttura, SEO e moduli |
media:read / media:write | Leggere / gestire media e cartelle |
settings:read / settings:write | Leggere / modificare impostazioni del sito |
users:read / users:write | Leggere / gestire utenti CMS |
leads:read / leads:write / analytics:read | Leggere / aggiornare contatti e leggere la dashboard CMS |
marketing:read / marketing:write | Leggere / generare contenuti marketing |
deployments:read / deployments:write | Processi di esportazione e pubblicazione della piattaforma |
sync:write / updates:read / updates:write | Sincronizzazione e aggiornamenti firmati delle installazioni indipendenti |
Salvare una bozza con l’SDK
Il pacchetto workspace è @qokit/site-api; non è ancora pubblicato su npm. Per progetti esterni, scarica entrambi i file client in sdk. Le nuove esportazioni li includono già.
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.mtsL’esempio richiede content:read e content:write. Sostituisci en con una lingua abilitata. Crea una nuova raccolta di esempio; nelle esecuzioni successive riutilizza un ID di raccolta esistente.
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);Il salvataggio di una bozza conserva l’istantanea pubblica precedente della voce pubblicata. Dopo la revisione, una chiave con content:publish può pubblicare esplicitamente la versione salvata. Le pagine della piattaforma restano bozze fino alla pubblicazione del sito.
await api.entries.publish(saved._id, { expectedUpdatedAt: saved.updatedAt });Per recuperare contenuti, leggi api.entries.revisions(id) e chiama api.entries.restore(id, revisionId, { expectedUpdatedAt }). Le altre operazioni documentate usano api.request(path, options), con idempotencyKey. Il client non ritenta automaticamente le scritture.
Rotte di gestione
Aggiungi il prefisso /v1/projects/{id} a questi percorsi. OpenAPI elenca operazioni, campi e requisiti specifici. DELETE archivia raccolte, voci e media.
| Percorso | Metodo |
|---|---|
/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 |
La piattaforma supporta registrazione URL e intenzioni di caricamento; i caricamenti indipendenti usano fileName, contentType e contentBase64, con limite di 10 MB e controllo della firma. Le modifiche degli utenti piattaforma richiedono Idempotency-Key; gli utenti locali una password di 12–1024 caratteri. CSV, scritture in blocco e collegamenti di traduzione sono estensioni della piattaforma.
Versioni, paginazione ed errori
Aggiornamenti, archiviazioni e ripristini richiedono expectedUpdatedAt dall’ultimo updatedAt letto. La versione mancante restituisce 428; quella obsoleta 409.
Per struttura, SEO e moduli, leggi GET /v1/projects/{id}/runtime e invia content.updatedAt e siteVersion.updatedAt come baseContentUpdatedAt e baseSiteVersionUpdatedAt. Restano validi i controlli di revisione e del lease di modifica attivo di Builder.
Le liste usano page=1&pageSize=24 per impostazione predefinita, fino a 100 elementi per pagina. La gestione restituisce items; le liste pubbliche entries. Revisioni e cartelle restituiscono array. Leggi tutte le pagine per esportare i contenuti.
{"items":[],"page":1,"pageSize":24,"total":0,"totalPages":1}Le risposte includono X-Request-Id e X-Qokit-Api-Version. Gli errori hanno un codice stabile e un ID di richiesta:
{"statusCode":409,"message":"This resource changed.","error":{"code":"CONFLICT","message":"This resource changed.","requestId":"request-id"}}Per 401, verifica la chiave; per 403, permessi e accesso del creatore. Per 409, rileggi e confronta le modifiche; per 428, fornisci la versione. Per 429, rispetta Retry-After. Il limite è 300 richieste al minuto per chiave/indirizzo, oltre ai limiti IP e scrittura della piattaforma.
Configurare l’installazione indipendente
La piattaforma usa CORS_ALLOWED_ORIGINS per il browser. Le chiamate indipendenti con chiave richiedono origini esatte in SITE_API_ALLOWED_ORIGINS; la gestione con Cookie resta sulla stessa origine. Le letture pubbliche CMS possono usare CMS_ALLOWED_ORIGINS. Per URL dei media CMS-only configura CMS_PUBLIC_URL.
Esegui il backup di tutti i dati e caricamenti, inclusi i file privati data/api-security.json e data/api-revisions.json. Password e chiavi restano locali come hash. Ogni directory dati ha un solo processo Node scrittore.
Le vecchie esportazioni ottengono v1 con un aggiornamento firmato del runtime. Dopo l’aggiornamento, scarica contratto e client attuali via HTTP; i file del pacchetto restano istantanee dell’esportazione.
Per letture pubbliche senza credenziali, consulta Chiamare l’API pubblica dei contenuti.
Ultimo aggiornamento il