বিষয়বস্তুলৈ যাওক
Quireনথিপত্ৰ
অসমীয়া

বিকাশকৰ গাইড

Quire REST API, OAuth, webhook, MCP server আৰু extension।

Markdown হিচাপে চাওক

আপোনাৰ প্ৰতিষ্ঠানৰ API ঠিকনা আৰু সীমিত scope-ৰ credential ব্যৱহাৰ কৰক। Read request-ৰ পৰা আৰম্ভ কৰি response পৰীক্ষা কৰক আৰু secret source control আৰু documentation-ৰ উদাহৰণৰ বাহিৰত ৰাখক।

Quire-ৰ এটা public API আছে: HTTPS-ৰ ওপৰত REST, OpenAPI 3.1 document-এ বৰ্ণনা কৰে; event-ৰ বাবে signed webhook আৰু AI assistant-ৰ বাবে MCP server আছে। API তথ্যসূত্ৰ-ত প্ৰতিটো endpoint আৰু event তালিকাভুক্ত।

ঠিকনা

প্ৰতিটো প্ৰতিষ্ঠানৰ নিজা ঠিকনা থাকে আৰু API ইয়াৰ তলত থাকে:

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

Credential-এ প্ৰতিষ্ঠান নিৰ্ধাৰণ কৰে। এটা প্ৰতিষ্ঠানৰ key আনটোৰ ঠিকনাত ব্যৱহাৰ কৰিলে নাকচ হয়।

যিকোনো প্ৰতিষ্ঠানৰ ঠিকনাত /api/v1/openapi.jsonত OpenAPI document পোৱা যায়, সেয়ে client generator-এ আপুনি call কৰা version-টো সদায় দেখে।

প্ৰমাণীকৰণ

API key script আৰু server-to-server integration-ৰ বাবে। প্ৰশাসকে /admin/integrations/api-keysত এটা সৃষ্টি কৰি scope বাছি এবাৰ দেখে। Bearer token হিচাপে পঠিয়াওক:

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

Key qk_live_ বা qk_test_ৰে আৰম্ভ হয়। প্ৰতিটো integration-ৰ নিজা key দিয়ক।

OAuth 2.1 ছাইন-ইন কৰা ব্যক্তিৰ হৈ কাম কৰা application-ৰ বাবে। /admin/integrations/oauth-clientsত client register কৰি PKCE (/oauth/authorize, /oauth/token)-সহ authorization code flow, অথবা machine client-ৰ বাবে client credentials ব্যৱহাৰ কৰক। Discovery /.well-known/oauth-authorization-serverত। Scope-এ token-এ কি কৰিব পাৰে সংকুচিত কৰে; ব্যক্তিজনে কৰিব পৰাতকৈ অধিক কৰিব নিদিয়ে।

Scope-সমূহ resource:read, resource:write আৰু resource:delete, যেনে courses:read বা enrolments:write। চাৰিটা privileged আৰু consent screen-ত সতৰ্কবাণীসহ দেখুওৱা হয়: audit:read, roles:write, tenants:write আৰু users:delete।

The API keys page with one key, the person it acts as, its scopes and its status, and a form to create another.
API keys list who each key acts as and what it may reach.

Request

  • Pagination: প্ৰতিটো list cursor pagination-যুক্ত। limit দিয়ক, তাৰ পিছত next_cursor থকা pageৰ পৰা cursor হিচাপে পঠিয়াওক, has_more true থকালৈ (তলৰ উদাহৰণ)। Offset নাই।
  • ইয়াৰ পিছৰ পৰিৱৰ্তন: updated_since-এ এটা সময়ৰ পিছত সলনি হোৱা বস্তু দিয়ে। মচা বস্তু জানিবলৈ include_deleted=true যোগ কৰক, অথবা /<resource>/deletions পঢ়ক।
  • External identifier: বেছিভাগ resource-এ আপোনাৰ external_id গ্ৰহণ কৰে; /<resource>/ext:{external_id}-এ তাৰ অনুসৰি পঢ়ে বা upsert কৰে, যাতে sync-ত Quire identifier ৰাখিব নালাগে।
  • Idempotency: Idempotency-Key header POST, PATCH আৰু DELETE request-ত পঠিয়াওক। একে key-ৰে retry কৰিলে কাম দুবাৰ নকৰি প্ৰথম response ঘূৰাই দিয়ে। Bulk endpoint-ত এইটো বাধ্যতামূলক।
  • Version: Major version path-ত (/v1) থাকে। ইয়াৰ ভিতৰত backward incompatible প্ৰতিটো পৰিৱৰ্তন তাৰিখযুক্ত revision; Quire-Version header-ৰে বাছক, যেনে Quire-Version: 2026-09-20। Header নিদিলে credential জাৰি কৰাৰ সময়ৰ revision পাব।

List-ৰ এটা page:

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

Error

প্ৰতিটো error RFC 9457 problem document:

{"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 অনুসৰি branch কৰক; detail মানুহৰ বাবে লিখা, দেখুৱাবলৈ নিৰাপদ আৰু সলনি হ’ব পাৰে। Code চিনিব নোৱাৰিলে category অনুসৰি ভাগ কৰক:

Category Status Retry
validation 422, errorsত field detail-সহ নহয়
authentication 401 নহয়
authorization 403 নহয়
not_found 404 নহয়
conflict 409 কেতিয়াবা
precondition 412 নহয়
quota plan-ৰ বাবে 402, size-ৰ বাবে 413 নহয়
rate_limit 429, Retry-After-সহ হয়
upstream 502 বা 504 হয়
internal 500 হয়

Support-ৰ সৈতে যোগাযোগ কৰোঁতে request_id উল্লেখ কৰক।

Webhook

/admin/webhooksত অথবা API-ৰ /webhook_subscriptionsত subscribe কৰক। Event নাম অনুসৰি (enrolment.created), এলেকা অনুসৰি (enrolment.*) বা সকলো (*) বাছক। Quire-এ প্ৰথমে webhook.ping পঠিয়ায়; আপোনাৰ endpoint-এ উত্তৰ দিলেহে subscription আৰম্ভ হয়।

Delivery-সমূহে Standard Webhooks specification অনুসৰণ কৰে:

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

Delivery verify কৰিবলৈ:

  1. JSON parse কৰাৰ আগতে পোৱা হুবহু byte-ৰে {webhook-id}.{webhook-timestamp}.{raw body} string বনাওক।
  2. Subscription secret-ৰে ইয়াৰ ওপৰত HMAC-SHA256 গণনা কৰি base64 কৰক।
  3. প্ৰতিটো v1, value-ৰ সৈতে webhook-signatureৰ value constant time-ত তুলনা কৰক। Secret rotation-ত দুটা থাকিব পাৰে; যিকোনো এটা মিলা মান্য।
  4. আপোনাৰ clock-ৰ পৰা পাঁচ মিনিটতকৈ বেছি আঁতৰি থকা 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 আঁতৰাওক: delivery এবাৰতকৈ অধিক আহিব পাৰে। Body-ত identifier আৰু চুটি সাৰাংশ থাকে; বৰ্তমান অৱস্থাৰ বাবে resource fetch কৰক। বিফল delivery-ৰ 72 ঘণ্টালৈকে backoff-সহ retry হয় আৰু delivery log-ৰ পৰা replay কৰিব পাৰি।

MCP

Quire-ৰ MCP server প্ৰতিষ্ঠানৰ ঠিকনাৰ /mcpত streamable HTTP-ৰে থাকে। MCP client-এ /.well-known/oauth-protected-resourceৰ পৰা OAuth server বিচাৰে; যিকোনো OAuth client-ৰ দৰে ব্যক্তিয়ে sign in কৰি consent দিয়ে। Tool-সমূহ ব্যক্তিজনৰ permission-সহ চলে আৰু ধ্বংসাত্মক tool-এ নিশ্চিতকৰণ বিচাৰে। প্ৰশাসকে /admin/integrations/mcpত উপলব্ধ tool বাছে।

The AI assistants page with the server address to give an assistant and a table of the tools it can use.
AI assistants (MCP): the server address, and the tools an assistant may call.

Plan আৰু API

API key, OAuth client, webhook আৰু MCP server plan-ৰ API entitlement-ৰ অন্তৰ্গত; প্ৰতিটো standard plan-ত ই থাকে। নথকা plan-ত key, client বা subscription সৃষ্টি নাকচ হয়, REST write আৰু MCP connection নাকচ হয়; data export কৰিব পৰা থাকিবলৈ REST read চলি থাকে। নাকচটো commerce.plan_entitlement code থকা precondition category-ৰ problem document।

Extension

Quire-ৰ নিজৰ activity type, block, enrolment method, sign-in method, question type, report, theme আৰু integration-সমূহ self-hosted installation-এ যোগ কৰিব পৰা একেটা extension registry-ৰ জৰিয়তে ঘোষণা হয়। Extension compile কৰি অন্তৰ্ভুক্ত কৰা হয়: runtime plugin loader নাই, hosted প্ৰতিষ্ঠানে যোগ কৰিব নোৱাৰে। প্ৰশাসকে /admin/extensionsত নিজৰ প্ৰতিষ্ঠানৰ বাবে প্ৰতিটো extension on বা off কৰে (চাওক প্ৰশাসকৰ গাইড)।

এটা লিখিবলৈ packages/integration/extensions/src/sample.tsৰ sample block আৰু theme-ৰ পৰা আৰম্ভ কৰক। Extension point বাছি points.tsৰ contract পঢ়ক; তাৰ পিছত ID, version, licence, কি দিয়ে আৰু লাগে, লগতে প্ৰতিষ্ঠানে off কৰিব পাৰেনে, এইবোৰসহ extension ঘোষণা কৰক। Web application আৰু worker একেলগ কৰা ঠাইত register কৰক, যাতে দুয়ো একমত হয়। Build কৰাৰ সময়ত আৰু প্ৰতিবাৰ register call-ত registry-এ point-ৰ নিয়ম পৰীক্ষা কৰে; সমস্যা নামসহ অবৈধ set নাকচ কৰে আৰু নাকচ কৰিলে registry সলনি নকৰে। Extension-ৰ নিজৰ test-এ ইয়াৰ বাবে extensionContractProblems খালী আৰু off কৰিলে ইয়াৰ প্ৰভাৱিত বস্তু সলনি হোৱা নিশ্চিত কৰিব লাগে।

নেভিগেচন

বিচাৰিবলৈ লিখক…

↑↓ নেভিগেট কৰক↵ বাছকEsc বন্ধ কৰক