Norsk
English Norsk Dansk

Velg språk

English Norsk Dansk

Kom i gang

Vis som Markdown Sidens .md-fil llms.txt Alle sider, for AI-verktøy Åpne i ChatGPT Still spørsmål om siden Åpne i Claude Still spørsmål om siden

PLAS kobler bibliotekets datakilder til tjenestene lånere og ansatte bruker. Her finner du din plass i modellen og veien til det første kallet.

Provider API v0.6.7 Sist oppdatert

Tre veier inn

Hvilket API du jobber med, avhenger av hvilken ende du bygger. Spesifikasjonen er den samme hos alle bibliotekssystemer som implementerer den.

  • Provider API · Vendor API

    Du bygger en tjeneste

    En app, et nettsted, selvbetjening, en infoskjerm eller et verktøy for de ansatte. Du kaller Provider API-et og implementerer Vendor API-et hvis tjenesten bruker SSO eller hendelser.

    Følg de fire trinnene

  • Provider API

    Du leverer systemet

    Bibliotekssystemet implementerer Provider API-et: operasjonene, token-endepunktet og hvordan kallere skilles fra hverandre.

    Implementer API-et

  • Search API · Content API

    Du leverer data

    Søk eller arrangementer. Search API og Content API er utsnitt av Provider API-ets operasjoner, hver med sin egen spesifikasjon. Spesifikasjonen nevner selv at for eksempel søket kan overlates til en tredjepart.

    Se de fire API-ene

Første kall i fire trinn

Trinnene gjelder Provider API-et i versjonen som er i produksjon. Detaljene til hvert trinn står i avsnittene nedenfor.

  1. Få tilgang

    Base-URL-en og dine client credentials kommer fra provideren — leverandøren av bibliotekssystemet, som implementerer token-endepunktet. Spesifikasjonen har ingen felles base-URL.

  2. Sjekk versjonen

    Kallet krever ikke token og svarer med versjonen provideren anbefaler — en første sjekk av forbindelsen før du autentiserer.

  3. Hent et token

    Send client credentials, og få et Bearer-token tilbake. Det skal med i Authorization-headeren på kallene etterpå.

  4. Gjør det første kallet

    Konfigurasjonen forteller hva bibliotekssystemet har slått på — for eksempel utlån, innlevering og hvilke identitetsleverandører som kan brukes. Før utlån og innlevering krever spesifikasjonen at tjenesten finner dem slått på her.

Usikker på hvilke kall tjenesten din trenger? Funksjonene tar utgangspunkt i det du vil bygge og viser kallene bak hver funksjon. Spesifikasjonen sier selv at den fortsatt er under arbeid, og at felter og struktur kan endre seg — alle versjoner står med OpenAPI-filen sin på API-oversikten, og changeloggen sier hva som endret seg i hver.

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 og credentials per leverandør, slik at samme tjeneste 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, og tokenet sendes med på kallene etterpå.

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 det kan brukes hvis en del av API-et (for eksempel søket) overlates til en tredjepart.
  • token_type — alltid Bearer.
  • expires_in — tokenets levetid i sekunder.

Bruk tokenet. Sett det i Authorization-headeren: Authorization: Bearer <access_token>. Bare tre operasjoner klarer seg uten: GetVersion, AuthenticateClient og RevokeToken.

Når det utløper. HTTP 401 betyr at tokenet mangler, er ugyldig eller er utløpt. Et token du ikke lenger trenger, trekkes tilbake med RevokeToken. Skjemaene står i referansen: AuthenticationClientCredentialsRequestBody og AuthenticationClientResponseBody.

Felles regler for alle kall

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

  • version (query, valgfri, på nesten alle operasjoner) — API-versjonen klienten forventer. Støtter ikke provideren den, svarer den med feilkode 600.
  • ui_language (query, valgfri, på operasjonene som angir den) — språket provideren returnerer tekster på. Kodene følger MARC-språklisten.
  • URL- og query-parametere forventes URL-kodede. En id med komma i en kommaseparert liste kodes derfor til %2C, mens kommaet mellom id-ene står som det er.
  • 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 bør ikke inneholde HTML, med mindre operasjonen uttrykkelig sier det.
  • Svar som er et map over id-ene du sendte, inneholder bare dem provideren kjenner. Ukjente id-er utelates; er alle ukjente, er svaret et tomt map.

Feil

Et feilsvar (HTTP 400) er et objekt med listen errors (Errors); hvert element har code og info (Error), og det første er det mest relevante. 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 alle i ErrorCode; flere operasjoner beskriver dem de kan gi.

HTTP-kodene 400, 401, 404 og 429 er delte svar og beskrives på versjonsoversikten. 401 finnes i to utgaver: et token som mangler, er ugyldig eller utløpt, og en mislykket klientpålogging på AuthenticateClient. En feil lånerpålogging har sin egen feilkode, 100001. 429 betyr at provideren begrenser antall kall — den er erklært på Checkin, Checkout og ChangePatronCredential; svaret bør angi i Retry-After hvor mange sekunder som må gå, og låneren skal se «prøv igjen senere», ikke en feil i det de har sendt.

Når bibliotekssystemet kaller tjenesten

Trafikken går også den andre veien. Det skjer gjennom Vendor API-et, og den delen implementerer tjenesten selv.

Implementerer du Provider API-et

Da er du provideren. Utover operasjonene beskriver spesifikasjonen fem ting du må ta stilling til — de to siste er anbefalinger fra sikkerhetsavsnittet.

  1. Token-endepunktet er ditt

    Spesifikasjonen sier at du bør implementere POST /authentication/oauth2/token og utstede tokens mot client credentials. Spesifikasjonen anbefaler et JWT, fordi det kan brukes hvis en del av API-et — for eksempel søket — overlates til en tredjepart.

  2. Du avgjør hvordan kallere skilles

    Spesifikasjonen nevner to måter: en base-URL per bibliotek og credentials per leverandør, eller én base-URL der credentials avgjør begge deler.

  3. Funksjoner kan slås av og på

    GetConfiguration forteller tjenesten hva som er slått på; før utlån og innlevering må tjenesten sjekke den. Feilkode 10001 betyr at en operasjon er slått av.

  4. En UUID som patronId

    Spesifikasjonen anbefaler sterkt en UUID — og, hvis systemet bruker heltall som låner-id, å legge en UUID ved siden av og bare bruke den i PLAS.

  5. Begrens påloggingsforsøk

    Rate limiting per låneridentifikator på POST /patron/authentication og POST /patron/authentication/no-password, og per låner når credentials tilbakestilles eller endres. Ved endring av credentials bør grensen svare med 429.

Neste skritt