Arendaja juhend

Kasuta oma organisatsiooni API-aadressi ja piiratud ulatusega mandaati. Alusta lugemispäringuga, kontrolli vastust ning hoia saladused lähtekoodist ja dokumentatsiooni näidetest väljas.

Quire’il on üks avalik API: HTTPS-i kaudu kasutatav REST, mida kirjeldab OpenAPI 3.1 dokument; sündmuste jaoks on allkirjastatud veebikonksud ning tehisintellekti assistentidele MCP-server. API viitedokumentatsioonis on loetletud kõik lõpp-punktid ja sündmused.

Aadressid

Igal organisatsioonil on oma aadress, mille all paikneb ka API:

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

Organisatsiooni määrab mandaat. Kui ühe organisatsiooni võtit kasutatakse teise organisatsiooni aadressil, lükatakse see tagasi.

OpenAPI dokumenti serveeritakse iga organisatsiooni aadressil /api/v1/openapi.json, nii et koodi genereerivad tööriistad näevad alati kasutatavat versiooni.

Autentimine

API võtmed sobivad skriptidele ja serveritevahelistele integratsioonidele. Haldur loob võtme aadressil /admin/integrations/api-keys, määrab selle ulatused ja näeb seda ühe korra. Saada see päises kandja märgina:

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

Võtmed algavad qk_live_ või qk_test_. Anna igale integratsioonile oma võti.

OAuth 2.1 sobib rakendustele, mis tegutsevad sisseloginud inimese nimel. Registreeri klient aadressil /admin/integrations/oauth-clients ning kasuta PKCE-ga autoriseerimiskoodi voogu (/oauth/authorize, /oauth/token) või masinklientide jaoks kliendi mandaati. Avastusdokument asub aadressil /.well-known/oauth-authorization-server. Ulatus piirab loa tegevusi; see ei anna kunagi inimese enda õigustest suuremaid õigusi.

Ulatused on resource:read, resource:write ja resource:delete, näiteks courses:read või enrolments:write. Neli privilegeeritud ulatust kuvatakse nõusolekuvaates hoiatusega: audit:read, roles:write, tenants:write ja users:delete.

Päringud

• Lehekülgede kaupa pärimine: kõik loendid kasutavad kursoripõhist lehekülgede kaupa pärimist. Anna limit ning seejärel edasta next_cursor väljast page järgmises päringus cursor-ina, kuni has_more on tõene (näide allpool). Nihkepiirangut pole.
• Muudatused alates ajast: updated_since tagastab pärast määratud aega muutunud andmed. Koos sellega kasuta valikut include_deleted=true või loe eemaldatute leidmiseks /<resource>/deletions.
• Välised tunnused: enamik ressursse lubab määrata enda external_id-i; aadress /<resource>/ext:{external_id} võimaldab selle alusel lugeda või lisada-uuendada, nii et sünkroonimisel pole vaja Quire’i tunnuseid salvestada.
• Korduste vältimine: saada päis Idempotency-Key päringuga POST, PATCH või DELETE. Sama võtmega korduspäring tagastab algse vastuse, selle asemel et toimingu uuesti teha. Hulgi-lõpp-punktid nõuavad seda.
• Versioonid: põhiversioon paikneb tees (/v1). Selle piires valitakse iga katkestav muudatus kuupäevaga versioonina päises Quire-Version, näiteks Quire-Version: 2026-09-20. Päise puudumisel saad mandaadi väljastamise ajal kehtinud versiooni.

Loendi üks lehekülg:

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

Tõrked

Kõik tõrked on RFC 9457 probleemidokumendid:

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

Haru vali code välja järgi, mis on püsiv; detail on inimestele mõeldud ohutu tekst, mis võib muutuda. Tundmatu koodi korral kasuta rühmitamiseks välja category:

Toe poole pöördudes lisa request_id.

Veebikonksud

Telli aadressil /admin/webhooks või API kaudu aadressil /webhook_subscriptions. Vali sündmused nime järgi (enrolment.created), valdkonna järgi (enrolment.*) või kõik (*). Quire saadab esmalt sündmuse webhook.ping; tellimus aktiveeritakse, kui sinu lõpp-punkt sellele vastab.

Edastused järgivad Standard Webhooks spetsifikatsiooni:

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

Edastuse kontrollimiseks:

1. Koosta string {webhook-id}.{webhook-timestamp}.{raw body} täpselt vastu võetud baitidest enne JSON-i parsimist.
2. Arvuta selle põhjal tellimuse saladusega HMAC-SHA256 ja kodeeri tulemus base64-vormingus.
3. Võrdle konstantse ajaga väärtust iga päise v1, väärtusega väljas webhook-signature. Saladuse vahetamise ajal võib neid olla kaks; sobib kumbki vaste.
4. Lükka tagasi ajatempel, mis erineb sinu kellaajast üle viie minuti.

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

Väldi kordusi webhook-id järgi: edastus võib saabuda mitu korda. Sisu sisaldab tunnuseid ja lühikest kokkuvõtet; praeguse oleku hankimiseks päringu ressurssi. Nurjunud edastusi proovitakse tagavaravahedega uuesti kuni 72 tundi; edastuslogist saab need ka uuesti käivitada.

MCP

Quire’i MCP-server asub organisatsiooni aadressil /mcp ja kasutab voogedastatavat HTTP-d. MCP-klient leiab OAuth-serveri aadressilt /.well-known/oauth-protected-resource; inimene logib sisse ja annab nõusoleku nagu iga OAuthi kliendi puhul. Tööriistad tegutsevad selle inimese õigustes ning hävitatavad toimingud küsivad kinnitust. Haldurid valivad saadaval tööriistad aadressil /admin/integrations/mcp.

Paketid ja API

API õiguse juurde kuuluvad API võtmed, OAuthi kliendid, veebikonksud ja MCP-server; see sisaldub igas tavapaketis. Paketis, mis seda ei sisalda, keeldutakse võtme, kliendi või tellimuse loomisest, REST-i kirjutuspäringutest ja MCP-ühendustest, kuid REST-i lugemispäringud töötavad edasi, et andmeid saaks eksportida. Keeld tagastatakse probleemidokumendina koodiga commerce.plan_entitlement, kategoorias precondition.

Laiendused

Quire’i enda tegevustüübid, plokid, registreerimis- ja sisselogimisviisid, küsimusetüübid, aruanded, kujundused ning integratsioonid deklareeritakse sama laienduste registri kaudu, mida saab ise majutatud paigaldusele täiendada. Laiendused kompileeritakse rakendusse: käitusajal pluginate laadijat pole ning majutatud organisatsioon ei saa ise laiendust lisada. Haldurid lülitavad laiendusi oma organisatsioonis sisse ja välja aadressil /admin/extensions (vt halduri juhendit).

Laienduse kirjutamiseks alusta näidisplokist ja kujundusest failis packages/integration/extensions/src/sample.ts. Vali laienduspunkt ja loe selle lepingut failist points.ts, seejärel deklareeri laiendus tunnuse, versiooni, litsentsi, pakutava ja vajaliku ning organisatsioonipoolse väljalülitamise lubatavusega. Registreeri see kohas, kus koostatakse veebirakendus ja töötlusteenus, et mõlemad kasutaksid sama seadistust. Register kontrollib ehitamisel ja iga register-kutse puhul laienduspunkti reegleid, keeldub kõigist kehtetutest kogumitest ning nimetab kõik probleemid; ebaõnnestumisel jääb register muutmata. Laienduse enda testid peaksid kinnitama, et selle extensionContractProblems on tühi ning väljalülitamine muudab vastavat funktsionaalsust.