ޑިވެލަޕަރ ގައިޑް

ތިބާގެ އޮގަނައިޒޭޝަންގެ API address އަދި scope ހުރި credential ބޭނުންކުރާށެވެ. ކިޔާ request އަކުން ފަށައި، response ޗެކްކޮށް، ސިކްރެޓް source control އަދި documentation ގެ example ތަކުން ބޭރަށް ބެހެއްޓާށެވެ.

ޤުއަރޭއަށް އެއް public API އެބަހުރި: HTTPS އިން REST، OpenAPI 3.1 document އިން އެންގި، event އަށް signed webhook އާއެކު، AI assistant އަށް MCP server އާއެކު. API reference އިން endpoint އަދި event ހުރިހާ ލިސްޓްކުރެއެވެ.

އެޑްރެސްތައް

ކޮންމެ އޮގަނައިޒޭޝަނަކަށް އަމިއްލަ address އެއްވެ، API އެތެރޭގައިވެއެވެ:

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

Credential އިން އޮގަނައިޒޭޝަން ނިންމައެވެ. އެއް އޮގަނައިޒޭޝަނަކުގެ key އެހެންކޮޅެއްގެ address ގައި ބޭނުންކުރިޔާ ރިޖެކްޓްކުރެވެއެވެ.

OpenAPI document އެއް ކޮންމެ އޮގަނައިޒޭޝަން address އަކުގައި /api/v1/openapi.json ގައި ދެއެވެ؛ އެހެންވެ client generator ތަކަށް ތިބާ ކޯލް ކުރާ version ހަމަ އެއީ ފެންނާނެއެވެ.

އެތެންޓިކޭޝަން

API key އަކީ script އަދި server-to-server integration އަށެވެ. Administrator އަކު /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 އާއެކު authorization code flow (/oauth/authorize، /oauth/token)، ނުވަތަ 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.

Requests

• ޕޭޖިނޭޝަން: ކޮންމެ list އެއް cursor paginated އެވެ. limit ދީ، ދެން next_cursor އަކީ page އިން ހޯދާ އަގެކެވެ؛ cursor ގައި އެއީ ފޮނުވާށެވެ އަދި has_more true ވާންދެން (މިސާލުން ތިރީގައި). Offset ނެތެވެ.
• ކުރިންވެސް ބަދަލުވި: updated_since އިން ވަގުތެއްގެ ފަހުން ބަދަލުވި ތަކެތި ދެއެވެ. include_deleted=true އާއެކު ބޭނުންކުރާ، ނުވަތަ /<resource>/deletions ކިޔާށެވެ، ފޮހިލި ތަކެތި ދަންނަން.
• External identifier: ގިނަ ރިސޯސް ތަކެއްގައި ތިބާގެ external_id ލިބެއެވެ، އަދި /<resource>/ext:{external_id} އިން އެއިން ކިޔައި ނުވަތަ upsert ކުރެއެވެ؛ sync އަށް ޤުއަރޭ identifier ތައް ސްޓޯރ ނުކުރެވޭނެއެވެ.
• Idempotency: Idempotency-Key header POST، PATCH އަދި DELETE ގައި ފޮނުވާށެވެ. އެއް key އާއެކު retry ކުރުމުން ފުރަތަމަ response އަނބުރައި، ވަކި ދެފަހަރު ކަން ނުކުރެއެވެ. Bulk endpoint އަށް މިއީ ލާޒިމެވެ.
• ވަރޝަން: major version path ގައި (/v1) ހުންނަނީ. އޭގެ ތެރޭގައި breaking change ކޮންމެއްގައިވެސް ތާރީޚުން version ހުންނާނެއެވެ؛ Quire-Version header އިން ހޮވާށެވެ، މިސާލަކަށް Quire-Version: 2026-09-20. Header ނެތްނަމަ credential ދިންއިރު އެވަގުތު ވަރޝަން ލިބެއެވެ.

ލިސްޓެއްގެ ޕޭޖެއް:

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

އެރަރުތައް

ކޮންމެ 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 މީހުނަށް ލިޔެ، އެމީހުނަށް ދައްކާން ސޭފްވެއެވެ، އަދި ބަދަލުވެދާނެއެވެ. ކޯޑެއް ނުދަންނަނަމަ category އިން bucket ކުރާށެވެ:

Support އާއި ގުޅާއިރު request_id ބުނާށެވެ.

Webhook

/admin/webhooks ގައި ނުވަތަ API އިން /webhook_subscriptions އަށް subscribe ކުރާށެވެ. enrolment.created ފަދަ event name ނުވަތަ enrolment.* ފަދަ area ނުވަތަ * ހޮވާށެވެ. ޤުއަރޭ ފުރަތަމަ webhook.ping ފޮނުވާނެއެވެ؛ އެތަނަށް endpoint ޖަވާބުދިން ފަހުން subscription ފެށެއެވެ.

Delivery ތައް Standard Webhooks specification އާއި އެއްގޮތް:

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

Delivery ވެރިފައިކުރުމަށް:

1. ފޮނުވި ހަމަ byte ތަކުން، JSON parse ކުރާ ކުރިން، {webhook-id}.{webhook-timestamp}.{raw body} string އެއް ހަދާށެވެ.
2. Subscription secret އާއެކު HMAC-SHA256 ހިސާބުކޮށް base64 ކުރާށެވެ.
3. v1, value ކޮންމެއްގައި webhook-signature އާއި constant time އިން compare ކުރާށެވެ. Secret rotation ވަގުތު ދެއް ވެދާނެ؛ އެއްވެސް އެއްގޮތް ވުމުން ފުދެއެވެ.
4. ތިބާގެ clock އާ ވާ 5 މިނިޓުން މަތި ފަރަގުވާ 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 އަކުން deduplicate ކުރާށެވެ؛ delivery އެއް ގިނަ ފަހަރުވެސް އައިސްދާނެއެވެ. Body ގައި identifier ތައް އަދި ކުޑަ summary އެއް ހުރެއެވެ؛ މިހާރުގެ ޙާލަތަށް resource ހޯދާށެވެ. ފޭލް ވި delivery ތައް 72 ގަޑިއިރަށް backoff އިން retry ކުރެވި، delivery log އިން replay ކުރެވޭނެއެވެ.

MCP

ޤުއަރޭ MCP server އަކީ އޮގަނައިޒޭޝަން address ގެ /mcp ގައި streamable HTTP އެވެ. MCP client އިން OAuth server /.well-known/oauth-protected-resource އިން ހޯދައި، މީހާ އެހެން OAuth client ފަދައިން sign in ކޮށް consent ދެއެވެ. Tool ތައް އެމީހާގެ permission އާއެކު އެމީހާގެ ފަރުވާގައި ހިންގައެވެ؛ ފޮހެލުމުފަދަ ކަމަކަށް ތައިދީ އެދެއެވެ. /admin/integrations/mcp ގައި އެޑްމިންނުން ލިބޭ ޓޫލްތައް ހޮވައެވެ.

ޕްލޭނާއި API

API key، OAuth client، webhook އަދި MCP server ޕްލޭންގެ API entitlement ގައިވެ، ކޮންމެ standard plan އެއްގައި އެއީ ހިމެނެއެވެ. ނެތް ޕްލޭނަކުގައި key، client ނުވަތަ subscription އުފައްދުން ރިޖެކްޓްކޮށް، REST write އަދި MCP connection މަނާކޮށް، ޑޭޓާ export ކުރެވޭން REST read އިތުރު ހުޅުވި ދެމިތިބެއެވެ. ރިޖެކްޝަންއަކީ problem document އެއް، commerce.plan_entitlement ކޯޑާއި precondition category އާއެކު.

Extensions

ޤުއަރޭގެ އަމިއްލަ activity type، block، enrolment method، sign-in method، question type، report، theme އަދި integration ތައް self-hosted installation އިން add ކުރެވޭ އެއް extension registry އިން ޑިކްލެއަރކުރެވެއެވެ. Extension ތައް compile ކުރެވިފައިވެއެވެ: runtime plugin loader ނެތެވެ، hosted organisation އަކު އަމިއްލަ އެއް އިތުރުނުކުރެވޭނެއެވެ. /admin/extensions ގައި ( administrator guide ބަލާށެވެ) އެޑްމިން އޮގަނައިޒޭޝަނަށް ކޮންމެ extension އެއް އޮން ނުވަތަ އޮފް ކުރެއެވެ.

Extension އެއް ލިޔުމަށް packages/integration/extensions/src/sample.ts ގެ sample block އަދި theme އިން ފެށާށެވެ. Extension point ހޮވައި points.ts ގައިވާ contract ކިޔައި، ID، version، licence، ކީއް ދޭނެތޯ، ކީއް ބޭނުންވާނެތޯ އަދި އޮގަނައިޒޭޝަނަކު އެއް އޮފް ކުރެވޭނެތޯ ޑިކްލެއަރކޮށް extension ހަދާށެވެ. Web application އަދި worker ގުޅުވޭ composition ތަނަކުގައި register ކުރާށެވެ، ދެތިން އެއްގޮތް ކަމަށް. Registry އެއް build ކުރާއިރާ register ކޯލް ކުރާއިރު point ގެ ޤާއިދަތައް ޗެކްކޮށް، ފޭލްވިޔާ ކޮންމެ މައްސަލައެއްގެ ނަން ދީ ރިޖެކްޓްކޮށް، registry އަނބުރާ ނުބަދަލުކުރެއެވެ. Extensionގެ އަމިއްލަ test އިން extensionContractProblems ހުސްކަން އަދި off ކުރުމުން އޭގެ އަސަރުވާ ތަކެތި ބަދަލުވާކަން assert ކުރާށެވެ.