Skip to Content
डेवलपर दस्तावेज़ीकरण

साइट / CMS API का उपयोग

प्लेटफ़ॉर्म या स्वतंत्र CMS में API v1 से प्रमाणीकरण, सामग्री संपादन और प्रकाशन करें।

साइट / CMS API का उपयोग

API v1 बाहरी एकीकरण को साइट और CMS डेटा से जोड़ता है। अपने परिनियोजन का अनुबंध पढ़ें, सीमित अधिकार वाली कुंजी बनाएँ और संस्करण सुरक्षा के साथ ड्राफ़्ट सहेजें।

सेवा और परिनियोजन चुनें

QOKIT_API_URL को API सेवा के origin (स्थानीय http://localhost:7777) या स्वतंत्र स्थापना के origin पर सेट करें। QOKIT_PROJECT_ID प्रोजेक्ट ID है; निर्यात इसे data/seed.json में project.id के रूप में रखता है। सार्वजनिक पढ़ना प्रोजेक्ट slug इस्तेमाल करता है।

परिनियोजनक्षमताएँ
प्लेटफ़ॉर्मCMS प्रबंधन, निर्यात और प्लेटफ़ॉर्म प्रकाशन
cms-managedस्थानीय CMS प्रबंधन और वेबसाइट रेंडरिंग
cms-onlyस्थानीय CMS प्रबंधन और सार्वजनिक headless पढ़ना; वेबसाइट रेंडरिंग नहीं
site-onlyस्थिर HTML पृष्ठ और संसाधन; रनटाइम API नहीं

अनुबंध खोजें

हर सेवा केवल समर्थित संचालन बताती है। अन्य संचालन 404 देते हैं। API 1.0 मौजूदा बिना संस्करण वाले रूट के साथ संगत रहता है।

पथउद्देश्य
GET /v1/openapi.jsonOpenAPI 3.1: अनुरोध बॉडी, उत्तर, अधिकार और पूर्वशर्तें
GET /v1/capabilitiesAPI संस्करण, परिनियोजन प्रकार और समर्थित संचालन
GET /v1/sdk/client.mjsनिर्भरता रहित JavaScript क्लाइंट
GET /v1/sdk/client.d.mtsसंबंधित TypeScript घोषणाएँ

API कुंजी बनाएँ

पूरा प्लेटफ़ॉर्म लॉगिन होने पर मिले accessToken को SESSION_TOKEN बनाएँ। खाते को साइट सेटिंग प्रबंधन का अधिकार चाहिए। कुंजी जारी करने से पहले आवश्यक प्रमाणीकरण पूरा करें।

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}'

स्वतंत्र CMS में परिनियोजन स्वामी के ईमेल और पासवर्ड से लॉगिन करें, सत्र Cookie सहेजें और कुंजी बनाएँ:

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}'

बनाते समय token केवल एक बार लौटता है। इसे सर्वर वातावरण चर QOKIT_SITE_API_KEY में रखें; अनुरोध qk_site_ से शुरू होने वाला Bearer token इस्तेमाल करते हैं। डिफ़ॉल्ट अवधि 90 दिन, सीमा 1–365 दिन और प्रति प्रोजेक्ट अधिकतम 50 सक्रिय कुंजियाँ हैं। सेटिंग प्रबंधन वाले लॉगिन सत्र से GET /v1/projects/{id}/api-keys द्वारा सूची और DELETE /v1/projects/{id}/api-keys/{keyId} द्वारा रद्द करें।

केवल आवश्यक अधिकार चुनें। हर अनुरोध पर निर्माता की वर्तमान पहुँच और अधिकार जाँचे जाते हैं। अवधि समाप्ति, रद्द करना और भूमिका बदलाव अगले अनुरोध से लागू होते हैं। API कुंजी दूसरी कुंजियाँ प्रबंधित नहीं कर सकती।

Scopeउद्देश्य
content:read / content:writeसंग्रह और प्रविष्टियाँ पढ़ें / संपादित करें
content:publishस्पष्ट प्रकाशन और प्रविष्टि प्रकाशित करने वाले लेखन
pages:read / pages:writeruntime पढ़ें / पृष्ठ सामग्री, संरचना, SEO और फ़ॉर्म संपादित करें
media:read / media:writeमीडिया और फ़ोल्डर पढ़ें / प्रबंधित करें
settings:read / settings:writeसाइट सेटिंग पढ़ें / बदलें
users:read / users:writeCMS उपयोगकर्ता पढ़ें / प्रबंधित करें
leads:read / leads:write / analytics:readलीड पढ़ें / अपडेट करें और CMS डैशबोर्ड पढ़ें
marketing:read / marketing:writeमार्केटिंग सामग्री पढ़ें / बनाएँ
deployments:read / deployments:writeप्लेटफ़ॉर्म निर्यात और प्रकाशन कार्य
sync:write / updates:read / updates:writeस्वतंत्र स्थापना सिंक और हस्ताक्षरित अपडेट

SDK से ड्राफ़्ट सहेजें

Workspace पैकेज @qokit/site-api अभी npm पर प्रकाशित नहीं हुआ है। बाहरी प्रोजेक्ट के लिए दोनों क्लाइंट फ़ाइलें sdk में डाउनलोड करें। नए निर्यात में ये शामिल हैं।

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

उदाहरण को content:read और content:write चाहिए। en की जगह प्रोजेक्ट की सक्रिय भाषा रखें। यह नया उदाहरण संग्रह बनाता है; अगली बार मौजूदा संग्रह 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);

ड्राफ़्ट सहेजना प्रकाशित प्रविष्टि का पिछला सार्वजनिक स्नैपशॉट बनाए रखता है। समीक्षा के बाद content:publish वाली कुंजी सहेजा संस्करण स्पष्ट रूप से प्रकाशित कर सकती है। प्लेटफ़ॉर्म पृष्ठ संपादन साइट प्रकाशन पूरा होने तक ड्राफ़्ट रहता है।

await api.entries.publish(saved._id, { expectedUpdatedAt: saved.updatedAt });

पुनर्प्राप्ति के लिए api.entries.revisions(id) पढ़ें और api.entries.restore(id, revisionId, { expectedUpdatedAt }) बुलाएँ। अन्य संचालन के लिए api.request(path, options) इस्तेमाल करें, जिसमें idempotencyKey समर्थित है। क्लाइंट लेखन स्वतः दोबारा नहीं करता।

प्रबंधन रूट

इन पथों में /v1/projects/{id} उपसर्ग जोड़ें। OpenAPI में सभी संचालन, फ़ील्ड और परिनियोजन आवश्यकताएँ हैं। DELETE संग्रह, प्रविष्टि और मीडिया को संग्रहित करता है।

पथविधि
/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

प्लेटफ़ॉर्म मीडिया URL पंजीकरण और अपलोड तैयारी देता है; स्वतंत्र अपलोड में fileName, contentType और contentBase64, 10 MB सीमा तथा फ़ाइल हस्ताक्षर जाँच है। प्लेटफ़ॉर्म उपयोगकर्ता बदलाव को Idempotency-Key चाहिए; स्थानीय उपयोगकर्ता के लिए 12–1024 अक्षर का पासवर्ड चाहिए। CSV, सामूहिक लेखन और अनुवाद संबंध प्लेटफ़ॉर्म विस्तार हैं।

संस्करण, पृष्ठांकन और त्रुटियाँ

अपडेट, संग्रहण और संशोधन बहाली के लिए expectedUpdatedAt में अंतिम पढ़े updatedAt का मान चाहिए। संस्करण न होने पर 428, पुराना होने पर 409 मिलता है।

संरचना, SEO और फ़ॉर्म के लिए GET /v1/projects/{id}/runtime पढ़ें, फिर content.updatedAt और siteVersion.updatedAt को baseContentUpdatedAt और baseSiteVersionUpdatedAt के रूप में भेजें। प्लेटफ़ॉर्म पर Builder संशोधन और सक्रिय संपादन लीज़ की जाँच जारी रहती है।

सूची का डिफ़ॉल्ट page=1&pageSize=24 और प्रति पृष्ठ अधिकतम 100 है। प्रबंधन सूची items, सार्वजनिक सूची entries लौटाती है। संशोधन और फ़ोल्डर arrays लौटाते हैं। निर्यात के लिए सभी पृष्ठ पढ़ें।

{"items":[],"page":1,"pageSize":24,"total":0,"totalPages":1}

उत्तर में X-Request-Id और X-Qokit-Api-Version होते हैं। त्रुटियों में स्थिर कोड और अनुरोध ID होता है:

{"statusCode":409,"message":"This resource changed.","error":{"code":"CONFLICT","message":"This resource changed.","requestId":"request-id"}}

401 पर कुंजी और 403 पर निर्माता की पहुँच व अधिकार जाँचें। 409 पर दोबारा पढ़कर बदलाव तुलना करें; 428 पर संस्करण दें। 429 पर Retry-After मानें। सीमा प्रति कुंजी/पते प्रति मिनट 300 अनुरोध है, साथ में प्लेटफ़ॉर्म IP और लेखन सीमाएँ हैं।

स्वतंत्र स्थापना की सेटिंग

प्लेटफ़ॉर्म ब्राउज़र एकीकरण CORS_ALLOWED_ORIGINS इस्तेमाल करता है। स्वतंत्र कुंजी वाले ब्राउज़र कॉल के लिए SITE_API_ALLOWED_ORIGINS में सटीक origin दें; Cookie प्रबंधन समान origin पर रहता है। सार्वजनिक CMS पढ़ना CMS_ALLOWED_ORIGINS भी इस्तेमाल कर सकता है। CMS-only मीडिया URL के लिए CMS_PUBLIC_URL सेट करें।

निजी data/api-security.json और data/api-revisions.json सहित पूरे डेटा फ़ोल्डर और अपलोड का बैकअप रखें। पासवर्ड और कुंजियाँ स्थानीय hash के रूप में रहती हैं। हर डेटा फ़ोल्डर में केवल एक Node प्रक्रिया लिखती है।

पुराने निर्यात को हस्ताक्षरित runtime अपडेट से v1 मिलता है। उसके बाद HTTP से वर्तमान अनुबंध और क्लाइंट डाउनलोड करें; पैकेज फ़ाइलें निर्यात समय के स्नैपशॉट हैं।

बिना क्रेडेंशियल सार्वजनिक पढ़ने के लिए देखें सार्वजनिक सामग्री API कॉल करें.

क्या यह गाइड उपयोगी थी?

अंतिम बार अपडेट किया गया:

इस पेज पर