Norsk
Norsk Dansk English
Norsk Dansk English

Kom i gang

Vis som Markdown Sidens .md-fil Åpne i ChatGPT Still spørsmål om siden Åpne i Claude Still spørsmål om siden

Det du må vite før det første kallet mot et bibliotekssystem som implementerer PLAS Provider API — og hvor referansen tar over derfra.

Provider API v0.6.5 Sist oppdatert

PLAS Provider API er grensesnittet et bibliotekssystem stiller til rådighet, slik at biblioteksprodukter kan lese og skrive låntakere, lån, reservasjoner og beholdning uten å kjenne systemet bak. Den som implementerer grensesnittet, kalles provideren; den som kaller det, kalles klienten. Denne siden er skrevet til klienten — det siste avsnittet til provideren.

Siden beskriver Provider API v0.6.5, den versjonen PLAS Status kaller i produksjon. v0.6.6 er i spesifikasjon. Spesifikasjonen sier selv at den fortsatt er under arbeid, og at felter og struktur kan endre seg.

Innhold

Forutsetninger

  • Et bibliotekssystem som implementerer Provider API v0.6.5.
  • Systemets base-URL og et sett client credentials (client_id og client_secret). Begge deler utleveres av provideren — det er den som avgjør hvem som får kalle.
  • Et verktøy som kan sende HTTP-kall og lese JSON.

Base-URL

Spesifikasjonen har ingen servers-blokk. Base-URL-en er providerens, ikke PLAS’, og den avtales med provideren. Alle stier i referansen — /version, /patron/{patronId}, /authentication/oauth2/token — er relative til den.

Spesifikasjonen beskriver to måter en provider kan kjenne kallerne sine på: en base-URL per bibliotek (slik at samme produkt kaller ulike adresser hos ulike bibliotek) eller én base-URL for alle, der credentials avgjør både bibliotek og leverandør. Regn derfor ikke med at base-URL-en er den samme fra bibliotek til bibliotek, heller ikke hos samme provider.

Autentisering

Provider API-et bruker OAuth 2.0 med client credentials. Ett kall gir et token; tokenet sendes med på alle andre kall.

Hent et token. Send en POST til /authentication/oauth2/token med Content-Type: application/x-www-form-urlencoded og tre felter: client_id, client_secret og grant_type med verdien client_credentials. Kallet krever ikke et token selv.

POST /authentication/oauth2/token
Content-Type: application/x-www-form-urlencoded

client_id=<client_id>&client_secret=<client_secret>&grant_type=client_credentials

Svaret er JSON med tre felter — alle påkrevde:

  • access_token — selve tokenet. Spesifikasjonen anbefaler provideren å utstede et JWT, slik at en tredjepart (for eksempel et søke-API) kan validere det uten å spørre provideren.
  • token_type — alltid Bearer.
  • expires_in — tokenets levetid i sekunder.

Bruk tokenet. Sett det i Authorization-headeren på hvert kall: Authorization: Bearer <access_token>.

Når det utløper. HTTP 401 betyr at tokenet mangler, er ugyldig eller er utløpt. Hent et nytt og prøv igjen. Skjemaene står i referansen: AuthenticationClientCredentialsRequestBody og AuthenticationClientResponseBody; operasjonen er AuthenticateClient.

Første kall

Start med GET /version. Det er det ene kallet som ikke krever et token, og svaret sier hvilken versjon av API-et provideren anbefaler — så du vet at base-URL-en er riktig, og hvilken versjon du skal be om, før du autentiserer.

Svaret har ett felt, version. Operasjonen er GetVersion.

Hent deretter et token, og kall den første operasjonen i gruppen produktet ditt trenger — for eksempel Patron for låntakerdata eller Holding for beholdning. Hver gruppe har sin egen side i referansen med parametere, request body og svar per operasjon.

Felles regler for alle kall

Disse reglene står én gang i spesifikasjonen og gjelder overalt. Den delte kontrakten — parametere og feilsvar som nesten alle operasjoner deler — står på versjonsoversikten.

  • version (query, valgfri) — API-versjonen klienten forventer. Støtter ikke provideren den, svarer den med feilkode 600. Send den; da oppdager du en versjonsforskjell som en feil i stedet for som et felt som mangler.
  • ui_language (query, valgfri) — språket provideren returnerer tekster på. Kodene følger MARC-språklisten.
  • URL- og query-parametere skal være URL-kodede. En id med komma i en kommaseparert liste kodes derfor til %2C.
  • Datoer og tidspunkter følger RFC 3339. Et tidspunkt skrives som date-time med stor T og eksplisitt tidssone — spesifikasjonen antar ingen. En ren dato skrives YYYY-MM-DD.
  • Svar inneholder ikke HTML, med mindre operasjonen uttrykkelig sier det.
  • Oppslag på en liste av id-er returnerer bare de id-ene provideren kjenner. Ukjente id-er utelates; er alle ukjente, er svaret et tomt map.

Feil

Et feilsvar har to felter, code og info (Error). Koden er et tall, og hele listen står i skjemaet ErrorCode. De tre du møter først:

  • 500 — systemfeil hos provideren.
  • 600 — versjonen du ba om, støttes ikke.
  • 10001 — operasjonen er slått av hos denne provideren.

Resten er domenespesifikke — for eksempel 100023 for en ukjent patronId og 102001 for et ukjent lån — og står på operasjonen de hører til. HTTP-kodene 400, 401 og 404 er delte svar og beskrives på versjonsoversikten.

Implementerer du API-et selv?

Da er du provideren, og spesifikasjonen gir tre anbefalinger utover selve operasjonene:

  • Bruk UUID som patronId. Bruker systemet heltall som låntaker-id, så legg en UUID ved siden av og bruk bare den i PLAS.
  • Beskytt låntakerpålogging mot brute force. POST /patron/authentication og POST /patron/authentication/no-password skal ha rate limiting per låntakeridentifikator.
  • Velg hvordan du kjenner kallerne dine — base-URL per bibliotek, credentials per leverandør, eller begge deler. Token-endepunktet /authentication/oauth2/token er ditt å implementere.

Neste skritt