Skip to Content
Dokumentasi pengembang

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.

PenerapanKemampuan
PlatformPengelolaan CMS, ekspor, dan publikasi platform
cms-managedPengelolaan CMS lokal dan rendering situs
cms-onlyPengelolaan CMS lokal dan pembacaan publik headless; tanpa rendering situs
site-onlyHalaman 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.

JalurTujuan
GET /v1/openapi.jsonOpenAPI 3.1: isi permintaan, respons, izin, dan prasyarat
GET /v1/capabilitiesVersi API, jenis penerapan, dan operasi tersedia
GET /v1/sdk/client.mjsKlien JavaScript tanpa dependensi
GET /v1/sdk/client.d.mtsDeklarasi 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.

ScopeTujuan
content:read / content:writeMembaca / mengedit koleksi dan entri
content:publishPublikasi eksplisit dan penulisan yang menerbitkan entri
pages:read / pages:writeMembaca runtime / mengedit konten, struktur, SEO, dan formulir
media:read / media:writeMembaca / mengelola media dan folder
settings:read / settings:writeMembaca / mengedit pengaturan situs
users:read / users:writeMembaca / mengelola pengguna CMS
leads:read / leads:write / analytics:readMembaca / memperbarui prospek dan membaca dasbor CMS
marketing:read / marketing:writeMembaca / menghasilkan konten pemasaran
deployments:read / deployments:writePekerjaan ekspor dan publikasi platform
sync:write / updates:read / updates:writeSinkronisasi 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.mts

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

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

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.

Apakah panduan ini membantu?

Terakhir diperbarui pada

Di halaman ini