Menggunakan API situs / CMS
Autentikasi, edit, dan publikasikan konten melalui API v1 di platform atau CMS mandiri.
Menggunakan API situs / CMS
API v1 menghubungkan integrasi eksternal ke data situs dan CMS. Baca kontrak penerapan, buat kunci dengan izin terbatas, lalu simpan draf dengan perlindungan versi.
Memilih layanan dan penerapan
Atur QOKIT_API_URL ke origin layanan API (lokal http://localhost:7777) atau instalasi mandiri. QOKIT_PROJECT_ID adalah ID proyek; ekspor menyimpannya di data/seed.json sebagai project.id. Pembacaan publik menggunakan slug proyek.
| Penerapan | Kemampuan |
|---|---|
| Platform | Pengelolaan CMS, ekspor, dan publikasi platform |
cms-managed | Pengelolaan CMS lokal dan rendering situs |
cms-only | Pengelolaan CMS lokal dan pembacaan publik headless; tanpa rendering situs |
site-only | Halaman HTML dan aset statis; tanpa API runtime |
Menemukan kontrak
Setiap layanan hanya mencantumkan operasi yang didukung. Operasi lain mengembalikan 404. API 1.0 tetap kompatibel dengan rute lama tanpa versi.
| Jalur | Tujuan |
|---|---|
GET /v1/openapi.json | OpenAPI 3.1: isi permintaan, respons, izin, dan prasyarat |
GET /v1/capabilities | Versi API, jenis penerapan, dan operasi tersedia |
GET /v1/sdk/client.mjs | Klien JavaScript tanpa dependensi |
GET /v1/sdk/client.d.mts | Deklarasi TypeScript yang sesuai |
Membuat kunci API
Gunakan accessToken dari login platform yang selesai sebagai SESSION_TOKEN. Akun memerlukan izin mengelola pengaturan situs. Selesaikan autentikasi yang diwajibkan sebelum membuat kunci.
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}'Pada CMS mandiri, login dengan email dan kata sandi pemilik penerapan, simpan Cookie sesi, lalu buat kunci:
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}'Pembuatan mengembalikan token sekali saja. Simpan sebagai variabel server QOKIT_SITE_API_KEY; permintaan memakai token Bearer berawalan qk_site_. Masa berlaku standar 90 hari, dapat diatur 1–365 hari, maksimal 50 kunci aktif per proyek. Gunakan sesi pengelola pengaturan untuk melihat melalui GET /v1/projects/{id}/api-keys dan mencabut melalui DELETE /v1/projects/{id}/api-keys/{keyId}.
Pilih hanya izin yang diperlukan. Akses dan izin terkini pembuat diperiksa pada setiap permintaan. Kedaluwarsa, pencabutan, dan perubahan peran berlaku pada permintaan berikutnya. Kunci API tidak dapat mengelola kunci lain.
| Scope | Tujuan |
|---|---|
content:read / content:write | Membaca / mengedit koleksi dan entri |
content:publish | Publikasi eksplisit dan penulisan yang menerbitkan entri |
pages:read / pages:write | Membaca runtime / mengedit konten, struktur, SEO, dan formulir |
media:read / media:write | Membaca / mengelola media dan folder |
settings:read / settings:write | Membaca / mengedit pengaturan situs |
users:read / users:write | Membaca / mengelola pengguna CMS |
leads:read / leads:write / analytics:read | Membaca / memperbarui prospek dan membaca dasbor CMS |
marketing:read / marketing:write | Membaca / menghasilkan konten pemasaran |
deployments:read / deployments:write | Pekerjaan ekspor dan publikasi platform |
sync:write / updates:read / updates:write | Sinkronisasi dan pembaruan bertanda tangan instalasi mandiri |
Menyimpan draf dengan SDK
Paket workspace adalah @qokit/site-api; belum dipublikasikan ke npm. Untuk proyek eksternal, unduh kedua file klien ke sdk. Ekspor baru sudah menyertakannya.
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.mtsContoh ini memerlukan content:read dan content:write. Ganti en dengan bahasa proyek yang aktif. Contoh membuat koleksi baru; pada eksekusi berikutnya gunakan ID koleksi yang sudah ada.
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);Menyimpan draf mempertahankan snapshot publik sebelumnya dari entri terbit. Setelah ditinjau, kunci dengan content:publish dapat menerbitkan versi tersimpan secara eksplisit. Edit halaman platform tetap menjadi draf sampai publikasi situs selesai.
await api.entries.publish(saved._id, { expectedUpdatedAt: saved.updatedAt });Untuk pemulihan, baca api.entries.revisions(id) lalu panggil api.entries.restore(id, revisionId, { expectedUpdatedAt }). Operasi lain menggunakan api.request(path, options), termasuk idempotencyKey. Klien tidak mengulangi penulisan secara otomatis.
Rute pengelolaan
Tambahkan awalan /v1/projects/{id} ke jalur ini. OpenAPI mencantumkan semua operasi, bidang, dan persyaratan penerapan. DELETE mengarsipkan koleksi, entri, dan media.
| Jalur | Metode |
|---|---|
/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 |
Media platform mendukung pendaftaran URL dan persiapan unggah; unggahan mandiri menggunakan fileName, contentType, dan contentBase64, dengan batas 10 MB dan pemeriksaan tanda tangan file. Perubahan pengguna platform memerlukan Idempotency-Key; pengguna lokal membutuhkan kata sandi 12–1024 karakter. CSV, penulisan massal, dan tautan terjemahan adalah ekstensi platform.
Versi, paginasi, dan kesalahan
Pembaruan, pengarsipan, dan pemulihan revisi membutuhkan expectedUpdatedAt dari updatedAt terakhir yang dibaca. Versi yang tidak ada menghasilkan 428; versi usang menghasilkan 409.
Untuk struktur, SEO, dan formulir, baca GET /v1/projects/{id}/runtime lalu kirim content.updatedAt dan siteVersion.updatedAt sebagai baseContentUpdatedAt dan baseSiteVersionUpdatedAt. Pemeriksaan revisi Builder dan sewa pengeditan aktif platform tetap berlaku.
Daftar memakai standar page=1&pageSize=24, maksimal 100 item per halaman. Daftar pengelolaan mengembalikan items, daftar publik entries. Revisi dan folder mengembalikan array. Baca semua halaman saat mengekspor konten.
{"items":[],"page":1,"pageSize":24,"total":0,"totalPages":1}Respons menyertakan X-Request-Id dan X-Qokit-Api-Version. Kesalahan memiliki kode tetap dan ID permintaan:
{"statusCode":409,"message":"This resource changed.","error":{"code":"CONFLICT","message":"This resource changed.","requestId":"request-id"}}Untuk 401, periksa kunci; untuk 403, izin dan akses pembuat. Untuk 409, baca ulang dan bandingkan perubahan; untuk 428, sertakan versi. Untuk 429, ikuti Retry-After. Batasnya 300 permintaan per menit per kunci/alamat, ditambah batas IP dan penulisan platform.
Konfigurasi instalasi mandiri
Integrasi browser platform memakai CORS_ALLOWED_ORIGINS. Panggilan browser mandiri dengan kunci memerlukan origin persis dalam SITE_API_ALLOWED_ORIGINS; pengelolaan Cookie tetap pada origin yang sama. Pembacaan CMS publik juga dapat memakai CMS_ALLOWED_ORIGINS. Untuk URL media CMS-only, atur CMS_PUBLIC_URL.
Cadangkan seluruh direktori data dan unggahan, termasuk file privat data/api-security.json dan data/api-revisions.json. Kata sandi dan kunci disimpan sebagai hash lokal. Setiap direktori data ditulis oleh satu proses Node.
Ekspor lama memperoleh v1 lewat pembaruan runtime bertanda tangan. Setelahnya, unduh kontrak dan klien terkini melalui HTTP; file paket tetap snapshot saat ekspor.
Untuk membaca konten publik tanpa kredensial, lihat Memanggil API konten publik.
Terakhir diperbarui pada