Gabay ng developer

Gamitin ang API address ng organisasyon mo at credential na may limitadong scope. Magsimula sa read request, tingnan ang tugon, at ilayo ang mga secret sa source control at mga halimbawa sa dokumentasyon.

Iisa ang pampublikong API ng Quire: REST sa HTTPS na inilalarawan ng dokumentong OpenAPI 3.1, pirmadong webhook para sa mga event, at MCP server para sa mga AI assistant. Inililista sa sanggunian ng API ang bawat endpoint at event.

Mga address

May sariling address ang bawat organisasyon at nasa ilalim nito ang API:

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

Tinutukoy ng credential ang organisasyon. Tatanggihan ang key ng isang organisasyon kapag ginamit sa address ng iba.

Ipinadadala ang dokumentong OpenAPI sa /api/v1/openapi.json sa address ng anumang organisasyon upang palaging makita ng mga client generator ang tinatawagan mong bersiyon.

Authentication

Para sa mga script at server-to-server integration ang API key. Gumagawa ang administrador nito sa /admin/integrations/api-keys, pumipili ng mga scope, at minsan lang ito nakikita. Ipadala ito bilang bearer token:

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

Nagsisimula sa qk_live_ o qk_test_ ang mga key. Bigyan ng sariling key ang bawat integration.

Para sa application na kumikilos bilang naka-sign in na tao ang OAuth 2.1. Magrehistro ng client sa /admin/integrations/oauth-clients, saka gamitin ang authorization code flow na may PKCE (/oauth/authorize, /oauth/token), o client credentials para sa machine client. Nasa /.well-known/oauth-authorization-server ang discovery. Nililimitahan ng scope ang kayang gawin ng token; hindi nito lalampasan ang mga pahintulot ng tao.

resource:read, resource:write, at resource:delete ang mga scope, halimbawa courses:read o enrolments:write. May apat na may pribilehiyo at ipinapakita kasama ang babala sa consent screen: audit:read, roles:write, tenants:write, at users:delete.

Mga request

• Pagination: gumagamit ng cursor pagination ang bawat list. Ipadala ang limit, saka ang next_cursor mula sa page bilang cursor habang true ang has_more (halimbawa sa ibaba). Walang offset.
• Mga pagbabago mula noon: ibinabalik ng updated_since ang mga binago pagkatapos ng oras. Isabay ang include_deleted=true, o basahin ang /<resource>/deletions, para malaman ang inalis.
• Mga external identifier: tinatanggap ng karamihan ng resource ang sarili mong external_id; binabasa o ini-upsert ito ng /<resource>/ext:{external_id} kaya hindi kailangang itago ng sync ang mga identifier ng Quire.
• Idempotency: ipadala ang Idempotency-Key header sa POST, PATCH, at DELETE. Ibinabalik ng retry na may kaparehong key ang unang response sa halip na ulitin ang trabaho. Kailangan ito ng bulk endpoint.
• Mga bersiyon: nasa path ang major version (/v1). Pumipili sa loob nito ng petsadong revision para sa bawat breaking change gamit ang header na Quire-Version, halimbawa Quire-Version: 2026-09-20. Kapag walang header, makukuha mo ang revision na kasalukuyan noong inilabas ang credential.

Isang pahina ng list:

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

Mga error

RFC 9457 problem document ang bawat error:

{"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..."}

Gamitin sa branching ang code, na hindi nagbabago; para sa tao ang detail, ligtas itong ipakita at maaari itong magbago. Kapag hindi mo kilala ang code, pangkatin ayon sa category:

Isama ang request_id kapag nakikipag-ugnayan sa support.

Mga webhook

Mag-subscribe sa /admin/webhooks o sa API sa /webhook_subscriptions. Piliin ang mga event ayon sa pangalan (enrolment.created), area (enrolment.*), o lahat (*). Nagpapadala muna ang Quire ng webhook.ping; magsisimula ang subscription kapag sinagot ito ng endpoint mo.

Sumusunod ang mga delivery sa Standard Webhooks specification:

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

Para beripikahin ang delivery:

1. Buuin ang string na {webhook-id}.{webhook-timestamp}.{raw body} mula sa eksaktong natanggap na bytes bago i-parse bilang JSON.
2. Kuwentahin ang HMAC-SHA256 dito gamit ang subscription secret at i-encode bilang base64.
3. Ihambing sa constant time sa bawat value na v1, ng webhook-signature. Maaaring dalawa ang mga ito habang nagpapalit ng secret; valid ang alinmang tumugma.
4. Tanggihan ang timestamp na lampas limang minuto ang layo sa oras mo.

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);
  });
}

Gumamit ng webhook-id para iwasan ang pagdoble: maaaring dumating nang higit sa isang beses ang delivery. May identifier at maikling buod ang body; kunin ang resource para sa kasalukuyan nitong estado. Muling sinusubukan nang may pagitan ang nabigong delivery nang hanggang 72 oras at maaari rin itong i-replay mula sa delivery log.

MCP

Nasa /mcp sa address ng organisasyon ang MCP server ng Quire at gumagamit ito ng streamable HTTP. Nadi-discover ng MCP client ang OAuth server mula sa /.well-known/oauth-protected-resource; mag-sign in at magbigay ng consent ang tao gaya ng sa alinmang OAuth client. Kumikilos ang mga tool bilang taong iyon, gamit ang mga pahintulot niya, at humihingi ng kumpirmasyon ang mapanirang tool. Pinipili ng mga administrador sa /admin/integrations/mcp kung aling tool ang magagamit.

Mga plan at ang API

Kasama sa API entitlement ng plan ang API key, OAuth client, webhook, at MCP server; kasama ito sa bawat karaniwang plan. Kapag wala ito sa plan, tatanggihan ang paggawa ng key, client, o subscription, pati ang REST write at MCP connection; magpapatuloy ang REST read upang mai-export ang data. Problem document ang pagtangging may code na commerce.plan_entitlement sa kategoryang precondition.

Mga extension

Idinedeklara ang sariling activity type, block, enrollment method, sign-in method, question type, report, theme, at integration ng Quire sa extension registry na maaaring dagdagan ng self-hosted na installation. Kino-compile ang mga extension: walang runtime plugin loader at hindi makapagdagdag nito ang hosted na organisasyon. Ino-on o ino-off ng mga administrador ang bawat extension para sa organisasyon sa /admin/extensions (tingnan ang gabay ng administrador).

Para magsulat nito, magsimula sa sample block at theme sa packages/integration/extensions/src/sample.ts. Piliin ang extension point at basahin ang contract nito sa points.ts, saka ideklara ang extension na may ID, bersiyon, lisensiya, ibinibigay at kailangan nito, at kung maaari itong i-off ng organisasyon. Irehistro ito sa composition ng web application at worker upang magkasundo ang dalawa. Sinusuri ng registry ang sariling tuntunin ng bawat point kapag binubuo at tuwing tatawagin ang register; tatanggihan nito ang invalid na set, ililista ang bawat problema, at pananatilihing hindi nagbabago ang registry. Dapat tiyakin ng mga test ng extension na walang laman ang extensionContractProblems para rito at binabago ng pag-off ang naaapektuhan nito.