Korzystanie z API witryny / CMS
Uwierzytelniaj, edytuj i publikuj treści przez API v1 na platformie lub w niezależnym CMS.
Korzystanie z API witryny / CMS
API v1 łączy integracje zewnętrzne z danymi witryny i CMS. Sprawdź kontrakt wdrożenia, utwórz klucz z ograniczonymi prawami i zapisz szkic z ochroną wersji.
Wybór usługi i wdrożenia
Ustaw QOKIT_API_URL na origin usługi API (lokalnie http://localhost:7777) lub niezależnej instalacji. QOKIT_PROJECT_ID to ID projektu; eksport zapisuje je w data/seed.json jako project.id. Publiczne odczyty używają projektu slug.
| Wdrożenie | Możliwości |
|---|---|
| Platforma | Zarządzanie CMS, eksporty i publikacja na platformie |
cms-managed | Lokalne zarządzanie CMS i renderowanie witryny |
cms-only | Lokalne zarządzanie CMS i publiczne odczyty headless; bez renderowania witryny |
site-only | Statyczne strony HTML i zasoby; bez API środowiska uruchomieniowego |
Odczyt kontraktu
Każda usługa opisuje tylko obsługiwane operacje. Pozostałe zwracają 404. API 1.0 zachowuje zgodność istniejących tras bez wersji.
| Ścieżka | Cel |
|---|---|
GET /v1/openapi.json | OpenAPI 3.1: treść żądania, odpowiedzi, uprawnienia i warunki wstępne |
GET /v1/capabilities | Wersja API, typ wdrożenia i dostępne operacje |
GET /v1/sdk/client.mjs | Klient JavaScript bez zależności |
GET /v1/sdk/client.d.mts | Odpowiadające deklaracje TypeScript |
Tworzenie klucza API
Użyj accessToken z zakończonego logowania na platformie jako SESSION_TOKEN. Konto wymaga praw zarządzania ustawieniami witryny. Przed wydaniem klucza zakończ wymagane uwierzytelnianie.
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}'W niezależnym CMS zaloguj się adresem e-mail i hasłem właściciela wdrożenia, zachowaj Cookie sesji i utwórz klucz:
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}'Podczas tworzenia token jest zwracany tylko raz. Zapisz go w zmiennej serwera QOKIT_SITE_API_KEY; żądania używają tokenów Bearer z prefiksem qk_site_. Domyślna ważność wynosi 90 dni, można ustawić 1–365 dni, maksymalnie 50 aktywnych kluczy na projekt. Sesją administratora ustawień wyświetlaj przez GET /v1/projects/{id}/api-keys i unieważniaj przez DELETE /v1/projects/{id}/api-keys/{keyId}.
Wybierz tylko potrzebne prawa. Każde żądanie sprawdza aktualny dostęp i uprawnienia twórcy. Wygaśnięcie, unieważnienie i zmiany roli działają na kolejne żądania. Klucze API nie zarządzają innymi kluczami.
| Scope | Cel |
|---|---|
content:read / content:write | Odczyt / edycja kolekcji i wpisów |
content:publish | Jawna publikacja i zapisy publikujące wpisy |
pages:read / pages:write | Odczyt runtime / edycja treści, struktury, SEO i formularzy |
media:read / media:write | Odczyt / zarządzanie mediami i folderami |
settings:read / settings:write | Odczyt / edycja ustawień witryny |
users:read / users:write | Odczyt / zarządzanie użytkownikami CMS |
leads:read / leads:write / analytics:read | Odczyt / aktualizacja leadów i odczyt panelu CMS |
marketing:read / marketing:write | Odczyt / generowanie treści marketingowych |
deployments:read / deployments:write | Zadania eksportu i publikacji platformy |
sync:write / updates:read / updates:write | Synchronizacja i podpisane aktualizacje niezależnych instalacji |
Zapis szkicu przez SDK
Pakiet workspace to @qokit/site-api; nie został jeszcze opublikowany w npm. W projekcie zewnętrznym pobierz oba pliki klienta do sdk. Nowe eksporty już je zawierają.
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.mtsPrzykład wymaga content:read i content:write. Zastąp en włączonym językiem projektu. Tworzy nową kolekcję przykładową; przy kolejnych uruchomieniach użyj istniejącego ID kolekcji.
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);Zapis szkicu zachowuje poprzedni publiczny snapshot opublikowanego wpisu. Po sprawdzeniu klucz z content:publish może jawnie opublikować zapisaną wersję. Strony platformy pozostają szkicami do ukończenia publikacji witryny.
await api.entries.publish(saved._id, { expectedUpdatedAt: saved.updatedAt });Aby odzyskać treści, odczytaj api.entries.revisions(id) i wywołaj api.entries.restore(id, revisionId, { expectedUpdatedAt }). Inne opisane operacje używają api.request(path, options), z obsługą idempotencyKey. Klient nie ponawia zapisów automatycznie.
Trasy zarządzania
Dodaj prefiks /v1/projects/{id} do tych ścieżek. OpenAPI opisuje wszystkie operacje, pola i wymagania danego wdrożenia. DELETE archiwizuje kolekcje, wpisy i media.
| Ścieżka | Metoda |
|---|---|
/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 |
Platforma obsługuje rejestrację URL i przygotowanie przesyłania; niezależne przesyłanie używa fileName, contentType i contentBase64, z limitem 10 MB i weryfikacją sygnatury. Zmiany użytkowników platformy wymagają Idempotency-Key; lokalni użytkownicy hasła o długości 12–1024 znaków. CSV, zapisy zbiorcze i powiązania tłumaczeń są rozszerzeniami platformy.
Wersje, paginacja i błędy
Aktualizacje, archiwizacja i przywracanie rewizji wymagają expectedUpdatedAt z ostatnio odczytanego updatedAt. Brak wersji zwraca 428, nieaktualna wersja 409.
Dla struktury, SEO i formularzy odczytaj GET /v1/projects/{id}/runtime i prześlij content.updatedAt oraz siteVersion.updatedAt jako baseContentUpdatedAt oraz baseSiteVersionUpdatedAt. Na platformie nadal obowiązują kontrole rewizji Builder i aktywnej dzierżawy edycji.
Listy domyślnie używają page=1&pageSize=24, maksymalnie 100 elementów na stronę. Zarządzanie zwraca items, listy publiczne entries. Rewizje i foldery zwracają tablice. Przy eksporcie odczytaj wszystkie strony.
{"items":[],"page":1,"pageSize":24,"total":0,"totalPages":1}Odpowiedzi zawierają X-Request-Id i X-Qokit-Api-Version. Błędy mają stały kod oraz ID żądania:
{"statusCode":409,"message":"This resource changed.","error":{"code":"CONFLICT","message":"This resource changed.","requestId":"request-id"}}Dla 401 sprawdź klucz, dla 403 uprawnienia i dostęp twórcy. Przy 409 odczytaj ponownie i porównaj zmiany; dla 428 podaj wersję. Przy 429 stosuj Retry-After. Limit wynosi 300 żądań na minutę na klucz/adres, z dodatkowymi limitami IP i zapisu platformy.
Konfiguracja niezależnej instalacji
Platforma używa CORS_ALLOWED_ORIGINS dla integracji przeglądarkowych. Niezależne wywołania z kluczem wymagają dokładnych originów w SITE_API_ALLOWED_ORIGINS; zarządzanie przez Cookie pozostaje w tym samym originie. Publiczne odczyty CMS mogą używać CMS_ALLOWED_ORIGINS. Dla adresów mediów CMS-only skonfiguruj CMS_PUBLIC_URL.
Wykonuj kopie wszystkich danych i przesłanych plików, w tym prywatnych data/api-security.json i data/api-revisions.json. Hasła i klucze pozostają lokalnie jako hashe. Jeden proces Node zapisuje w każdym katalogu danych.
Starsze eksporty uzyskują v1 przez podpisaną aktualizację runtime. Następnie pobierz aktualny kontrakt i klienta przez HTTP; pliki pakietu pozostają snapshotami eksportu.
Publiczne odczyty bez poświadczeń opisuje Wywołanie publicznego API treści.
Ostatnia aktualizacja