Ontwikkelaarsgids

Gebruik jou organisasie se API-adres en ’n aanmeldbewys met beperkte omvang. Begin met ’n leesversoek, kontroleer die antwoord en hou geheime buite bronbeheer en dokumentasievoorbeelde.

Quire het een openbare API: REST oor HTTPS, beskryf deur ’n OpenAPI 3.1-dokument, met ondertekende webhooks vir gebeurtenisse en ’n MCP-bediener vir KI-assistente. Die API-verwysing lys elke eindpunt en gebeurtenis.

Adresse

Elke organisasie het sy eie adres, en die API is daaronder:

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

Die aanmeldbewys bepaal die organisasie. ’n Sleutel vir een organisasie wat by ’n ander se adres gebruik word, word geweier.

Die OpenAPI-dokument word by /api/v1/openapi.json op enige organisasie se adres bedien, sodat kliëntgenerators altyd die weergawe sien wat jy aanroep.

Verifikasie

API-sleutels is vir skrifte en bediener-tot-bediener-integrasies. ’n Administrateur skep een by /admin/integrations/api-keys, kies sy omvang en sien dit een keer. Stuur dit as ’n draerteken:

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

Sleutels begin met qk_live_ of qk_test_. Gee elke integrasie sy eie sleutel.

OAuth 2.1 is vir toepassings wat as ’n aangemelde persoon optree. Registreer ’n kliënt by /admin/integrations/oauth-clients, en gebruik dan die magtigingskodestroom met PKCE (/oauth/authorize, /oauth/token), of kliëntbewyse vir ’n masjienkliënt. Ontdekking is by /.well-known/oauth-authorization-server. ’n Omvang beperk wat ’n teken kan doen; dit laat dit nooit meer doen as wat die persoon kan nie.

Omvange is resource:read, resource:write en resource:delete, byvoorbeeld courses:read of enrolments:write. Vier is bevoorreg en word met ’n waarskuwing op die toestemmingskerm gewys: audit:read, roles:write, tenants:write en users:delete.

Versoeke

• Paginering: elke lys gebruik wyserpaginering. Stuur limit, en dan die next_cursor van page as cursor terwyl has_more waar is (voorbeeld hieronder). Daar is geen verskuiwingsnommer nie.
• Veranderinge sedert: updated_since gee terug wat ná ’n tyd verander het. Kombineer dit met include_deleted=true, of lees /<resource>/deletions, om uit te vind wat verwyder is.
• Eksterne identifiseerders: die meeste hulpbronne aanvaar jou eie external_id, en /<resource>/ext:{external_id} lees of skryf op grond daarvan, sodat ’n sinkronisering nooit Quire se identifiseerders hoef te stoor nie.
• Idempotensie: stuur ’n Idempotency-Key-opskrif by POST, PATCH en DELETE. ’n Herhaling met dieselfde sleutel gee die eerste antwoord terug in plaas daarvan om die werk twee keer te doen. Grootmaat-eindpunte vereis dit.
• Weergawes: die hoofweergawe is in die pad (/v1). Daarbinne is elke verandering wat nie agteruitversoenbaar is nie ’n gedateerde hersiening, gekies deur die Quire-Version-opskrif, byvoorbeeld Quire-Version: 2026-09-20. Sonder die opskrif kry jy die hersiening wat van krag was toe jou aanmeldbewys uitgereik is.

’n Lysbladsy:

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

Foute

Elke fout is ’n RFC 9457-probleemdokument:

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

Tak op grond van code, wat stabiel is; detail is vir mense geskryf, veilig om aan hulle te wys en kan verander. Wanneer jy ’n kode nie herken nie, groepeer volgens category:

Haal request_id aan wanneer jy ondersteuning kontak.

Webhooks

Teken in by /admin/webhooks, of deur die API by /webhook_subscriptions. Kies gebeurtenisse volgens naam (enrolment.created), area (enrolment.*) of alles (*). Quire stuur eers ’n webhook.ping; die intekening begin wanneer jou eindpunt daarop antwoord.

Aflewerings volg die Standard Webhooks-spesifikasie:

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

Om ’n aflewering te verifieer:

1. Bou die string {webhook-id}.{webhook-timestamp}.{raw body} uit die presiese ontvangde grepe, voordat enige JSON-ontleding plaasvind.
2. Bereken HMAC-SHA256 daaroor met jou intekeninggeheim en kodeer die resultaat as base64.
3. Vergelyk in konstante tyd met elke v1,-waarde in webhook-signature. Daar kan twee wees tydens ’n geheimrotasie; enige passing is geldig.
4. Verwerp ’n tydstempel wat meer as vyf minute van jou horlosie afwyk.

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

Verwyder duplikate volgens webhook-id: ’n aflewering kan meer as een keer aankom. Die liggaam bevat identifiseerders en ’n kort opsomming; haal die hulpbron op vir sy huidige toestand. Mislukte aflewerings word tot 72 uur lank met terugkeertye probeer, en kan weer vanaf die afleweringslog gespeel word.

MCP

Quire se MCP-bediener is by /mcp op die organisasie se adres, oor stroomvervoer-HTTP. ’n MCP-kliënt ontdek die OAuth-bediener deur /.well-known/oauth-protected-resource, en die persoon meld aan en gee toestemming soos met enige OAuth-kliënt. Nutsmiddels tree met daardie persoon se toestemmings op; vernietigende nutsmiddels vra bevestiging. Administrateurs kies beskikbare nutsmiddels by /admin/integrations/mcp.

Planne en die API

API-sleutels, OAuth-kliënte, webhooks en die MCP-bediener val onder die plan se API-regte, en elke standaardplan sluit dit in. Op ’n plan daarsonder word die skep van ’n sleutel, kliënt of intekening geweier; REST-skrywings en MCP-verbindings word geweier; REST-leesaksies bly werk sodat data uitvoerbaar bly. Die weiering is ’n probleemdokument met kode commerce.plan_entitlement in die kategorie precondition.

Uitbreidings

Quire se eie aktiwiteitsoorte, blokke, inskrywingsmetodes, aanmeldmetodes, vraagsoorte, verslae, temas en integrasies word verklaar deur dieselfde uitbreidingsregister waaraan ’n selfgehuisveste installasie kan byvoeg. Uitbreidings word saamgestel: daar is geen inprop-laaier tydens looptyd nie en ’n gehuisveste organisasie kan nie een byvoeg nie. Administrateurs skakel elke uitbreiding vir hul organisasie aan of af by /admin/extensions (sien die administrateursgids).

Om een te skryf, begin met die voorbeeldblok en -tema in packages/integration/extensions/src/sample.ts. Kies die uitbreidingspunt en lees die kontrak in points.ts; verklaar dan die uitbreiding met ’n ID, weergawe, lisensie, wat dit verskaf en vereis, en of ’n organisasie dit mag afskakel. Registreer dit waar die webtoepassing en werker saamgestel word, sodat albei ooreenstem. Die register kontroleer elke punt se eie reëls wanneer dit gebou word en elke keer wat jy register aanroep; dit weier ’n ongeldige stel, benoem elke probleem en laat die register onveranderd. Die uitbreiding se eie toetse behoort te bevestig dat extensionContractProblems daarvoor leeg is en dat die afskakeling daarvan verander wat dit beïnvloed.