डेवलपर मार्गदर्शिका

अपने संगठन का API पता और सीमित scope वाला क्रेडेंशियल इस्तेमाल करें। पढ़ने की रिक्वेस्ट से शुरू करें, जवाब जाँचें, और secrets को source control तथा दस्तावेज़ी उदाहरणों से बाहर रखें।

Quire का एक सार्वजनिक API है: HTTPS पर REST, OpenAPI 3.1 दस्तावेज़ में वर्णित, इवेंट के लिए हस्ताक्षरित webhooks और AI सहायकों के लिए MCP सर्वर सहित। API संदर्भ हर endpoint और इवेंट सूचीबद्ध करता है।

पते

हर संगठन का अपना पता होता है और API उसी के नीचे है:

https://acme.quirelms.com/api/v1/courses

क्रेडेंशियल संगठन तय करता है। एक संगठन की key दूसरे के पते पर इस्तेमाल करने पर अस्वीकार होती है।

OpenAPI दस्तावेज़ हर संगठन के पते पर /api/v1/openapi.json से मिलता है, ताकि client generator हमेशा वही संस्करण देखे जिसे आप कॉल कर रहे हैं।

प्रमाणीकरण

API keys स्क्रिप्ट और server-to-server एकीकरण के लिए हैं। प्रशासक /admin/integrations/api-keys पर एक बनाता है, उसके scopes चुनता है और उसे एक बार देखता है। उसे bearer token के रूप में भेजें:

curl -H "Authorization: Bearer qk_live_..." https://acme.quirelms.com/api/v1/users?limit=50

Keys qk_live_ या qk_test_ से शुरू होती हैं। हर एकीकरण को उसकी अपनी key दें।

OAuth 2.1 उन ऐप्लिकेशन के लिए है जो साइन-इन व्यक्ति के रूप में काम करते हैं। /admin/integrations/oauth-clients पर client रजिस्टर करें, फिर PKCE (/oauth/authorize, /oauth/token) के साथ authorization code flow या machine client के लिए client credentials इस्तेमाल करें। Discovery /.well-known/oauth-authorization-server पर है। Scope token के काम सीमित करता है; वह व्यक्ति की क्षमता से ज़्यादा कभी नहीं देता।

Scopes resource:read, resource:write और resource:delete हैं, उदाहरण के लिए courses:read या enrolments:write। चार privileged हैं और consent screen पर चेतावनी के साथ दिखते हैं: audit:read, roles:write, tenants:write और users:delete।

अनुरोध

• पृष्ठांकन: हर सूची cursor से पृष्ठांकित है। limit भेजें, फिर next_cursor (जो page में मिलता है) को cursor के रूप में भेजें जब तक has_more सही हो (उदाहरण नीचे)। कोई offset नहीं है।
• इसके बाद के बदलाव: updated_since किसी समय के बाद बदली चीज़ें लौटाता है। हटाई गई चीज़ जानने के लिए इसे include_deleted=true के साथ लें या /<resource>/deletions पढ़ें।
• बाहरी पहचानकर्ता: ज़्यादातर resources आपका external_id स्वीकार करते हैं; /<resource>/ext:{external_id} उसे पढ़ता या upsert करता है, इसलिए sync को Quire के identifiers सहेजने की ज़रूरत नहीं।
• Idempotency: Idempotency-Key header को POST, PATCH और DELETE के साथ भेजें। उसी key का retry पहला जवाब लौटाता है, काम दोबारा नहीं करता। Bulk endpoints को यह चाहिए।
• संस्करण: मुख्य संस्करण पथ में है (/v1)। इसके भीतर हर breaking change तारीख़ वाला revision है, जिसे Quire-Version header चुनता है, जैसे Quire-Version: 2026-09-20। Header न हो तो क्रेडेंशियल जारी होने के समय वाला revision मिलता है।

सूची का एक पृष्ठ:

{"data": [...], "page": {"next_cursor": "eyJ2Ijox...", "has_more": true, "limit": 100}}

त्रुटियाँ

हर त्रुटि RFC 9457 problem दस्तावेज़ है:

{"type": "https://quire.com/errors/enrolment.seat_limit_reached",
 "title": "Seat limit reached", "status": 409,
 "code": "enrolment.seat_limit_reached", "category": "conflict",
 "detail": "The course has no seats left, so this enrolment was not created. ...",
 "request_id": "01JB7XQK4Z..."}

code पर शाखा चुनें, जो स्थिर है; detail लोगों के लिए लिखा है, उन्हें दिखाना सुरक्षित है और बदल सकता है। अपरिचित code हो तो category से समूह बनाएँ:

सहायता से संपर्क करते समय request_id बताएँ।

Webhooks

/admin/webhooks पर या API के /webhook_subscriptions के ज़रिए subscribe करें। नाम (enrolment.created), पूरे क्षेत्र (enrolment.*) या सब (*) से इवेंट चुनें। पहले Quire webhook.ping भेजता है; आपका endpoint जवाब दे तब subscription शुरू होती है।

डिलीवरी Standard Webhooks specification का पालन करती हैं:

POST /hooks/quire
webhook-id: 01JB7XQK4Z8FQ2M3N4P5R6S7T8
webhook-timestamp: 1790000000
webhook-signature: v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=

डिलीवरी सत्यापित करने के लिए:

1. JSON पार्स करने से पहले, प्राप्त ठीक bytes से {webhook-id}.{webhook-timestamp}.{raw body} string बनाएँ।
2. Subscription secret से उस पर HMAC-SHA256 निकालकर base64 करें।
3. हर v1, मान की webhook-signature में constant time से तुलना करें। Secret बदलने के दौरान दो मान हो सकते हैं; किसी एक का मिलना मान्य है।
4. अपनी घड़ी से पाँच मिनट से अधिक अंतर वाला timestamp अस्वीकार करें।

import { createHmac, timingSafeEqual } from 'node:crypto';

function verify(secret, id, timestamp, rawBody, header) {
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const expected = createHmac('sha256', Buffer.from(secret.replace(/^whsec_/, ''), 'base64'))
    .update(`${id}.${timestamp}.${rawBody}`).digest();
  return header.split(' ').some((part) => {
    const [version, value] = part.split(',');
    const given = Buffer.from(value ?? '', 'base64');
    return version === 'v1' && given.length === expected.length && timingSafeEqual(given, expected);
  });
}

webhook-id पर duplicate रोकें: डिलीवरी एक से ज़्यादा बार आ सकती है। body में पहचानकर्ता और छोटा सारांश होता है; मौजूदा स्थिति के लिए resource लाएँ। विफल डिलीवरी 72 घंटे तक बढ़ते अंतराल पर फिर भेजी जाती हैं और delivery log से replay की जा सकती हैं।

MCP

Quire का MCP सर्वर संगठन के पते पर /mcp में streamable HTTP के ज़रिए है। MCP client OAuth सर्वर को /.well-known/oauth-protected-resource से खोजता है; व्यक्ति किसी भी OAuth client की तरह साइन इन करके सहमति देता है। Tools उस व्यक्ति की अनुमतियों के साथ उसी के रूप में काम करते हैं और नुकसानदेह tools पुष्टि माँगते हैं। प्रशासक /admin/integrations/mcp पर उपलब्ध tools चुनते हैं।

योजनाएँ और API

API keys, OAuth clients, webhooks और MCP सर्वर योजना के API entitlement में आते हैं, जो हर standard योजना में है। यह न हो तो key, client या subscription बनाने से मना किया जाता है, REST writes और MCP connections अस्वीकार होते हैं, और डेटा निर्यात योग्य रहे इसलिए REST reads चलते रहते हैं। इनकार commerce.plan_entitlement code वाले problem दस्तावेज़ में आता है, जिसकी श्रेणी precondition है।

एक्सटेंशन

Quire के गतिविधि प्रकार, blocks, नामांकन तरीके, साइन-इन तरीके, प्रश्न प्रकार, रिपोर्ट, थीम और एकीकरण उसी extension registry से घोषित होते हैं जिसमें अपने सर्वर पर चलने वाला इंस्टॉलेशन जोड़ सकता है। एक्सटेंशन compile होकर आते हैं: runtime plugin loader नहीं है और होस्टेड संगठन उन्हें जोड़ नहीं सकता। प्रशासक /admin/extensions पर संगठन के लिए हर एक्सटेंशन चालू या बंद करते हैं (देखें प्रशासक मार्गदर्शिका)।

एक लिखने के लिए packages/integration/extensions/src/sample.ts में sample block और theme से शुरू करें। Extension point चुनें और points.ts में उसका अनुबंध पढ़ें, फिर extension को id, version, licence, वह क्या देता और माँगता है, और संगठन उसे बंद कर सकता है या नहीं—इनके साथ घोषित करें। जहाँ web app और worker संयोजित होते हैं वहाँ उसे रजिस्टर करें ताकि दोनों सहमत हों। Registry बनते समय और हर register कॉल पर हर point के अपने नियम जाँचती है; अमान्य समूह को सभी समस्याएँ बताकर अस्वीकार करती है और registry अपरिवर्तित छोड़ती है। Extension के अपने tests को जाँचना चाहिए कि extensionContractProblems उसके लिए खाली है और उसे बंद करने से प्रभावित चीज़ बदलती है।