Dansk
English Norsk Dansk

Vælg sprog

English Norsk Dansk

Kom i gang

Vis som Markdown Sidens .md-fil llms.txt Alle sider, til AI-værktøjer Åbn i ChatGPT Stil spørgsmål om siden Åbn i Claude Stil spørgsmål om siden

PLAS forbinder bibliotekets datakilder med de tjenester brugere og medarbejdere møder. Her finder du din plads i modellen og vejen til det første kald.

Provider API v0.6.7 Sidst opdateret

Tre veje ind

Hvilket API du arbejder med, afhænger af hvilken ende du bygger. Specifikationen er den samme hos alle bibliotekssystemer der implementerer den.

  • Provider API · Vendor API

    Du bygger en tjeneste

    En app, en hjemmeside, selvbetjening, en infoskærm eller et medarbejderværktøj. Du kalder Provider API'et og implementerer Vendor API'et, hvis tjenesten bruger SSO eller hændelser.

    Følg de fire trin

  • Provider API

    Du leverer systemet

    Bibliotekssystemet implementerer Provider API'et: operationerne, token-endpointet og måden kaldere kendes fra hinanden på.

    Implementér API'et

  • Search API · Content API

    Du leverer data

    Søgning eller arrangementer. Search API og Content API er udsnit af Provider API'ets operationer, hver med sin egen specifikation. Spec'en nævner selv at fx søgningen kan overlades til en tredjepart.

    Se de fire API'er

Første kald i fire trin

Trinene gælder Provider API'et i den version der er i produktion. Detaljerne til hvert trin står i afsnittene nedenfor.

  1. Få adgang

    Base-URL'en og dine client credentials kommer fra provideren — leverandøren af bibliotekssystemet, som implementerer token-endpointet. Spec'en har ingen fælles base-URL.

  2. Tjek versionen

    Kaldet kræver ingen token og svarer med den version provideren anbefaler — et første tjek af forbindelsen, før du autentificerer.

  3. Hent en token

    Send dine client credentials, og få en Bearer-token tilbage. Den skal med i Authorization-headeren på kaldene derefter.

  4. Lav det første kald

    Konfigurationen fortæller hvad bibliotekssystemet har slået til — fx udlån, aflevering og hvilke identitetsudbydere der kan bruges. Før udlån og aflevering kræver spec'en at tjenesten finder dem slået til her.

Ved du ikke hvilke kald din tjeneste skal bruge? Funktionerne tager udgangspunkt i det du vil bygge og viser kaldene bag hver funktion. Spec'en siger selv at den stadig er under arbejde, og at felter og struktur kan ændre sig — alle versioner står med deres OpenAPI-fil på API-oversigten, og changeloggen siger hvad der ændrede sig i hver.

Base-URL

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

Spec’en beskriver to måder en provider kan kende sine kaldere på: en base-URL pr. bibliotek og credentials pr. leverandør, så samme tjeneste kalder forskellige adresser hos forskellige biblioteker, eller én base-URL for alle, hvor credentials afgør både bibliotek og leverandør. Regn derfor ikke med at base-URL’en er den samme fra bibliotek til bibliotek, selv hos samme provider.

Autentificering

Provider API’et bruger OAuth 2.0 med client credentials. Ét kald giver en token, og tokenen sendes med på kaldene derefter.

Hent en token. Send et POST til /authentication/oauth2/token med Content-Type: application/x-www-form-urlencoded og tre felter: client_id, client_secret og grant_type med værdien client_credentials. Kaldet kræver ikke selv en token.

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åkrævede:

  • access_token — selve tokenen. Spec’en anbefaler provideren at udstede en JWT, så den kan bruges hvis en del af API’et (fx søgningen) overlades til en tredjepart.
  • token_type — altid Bearer.
  • expires_in — tokenens levetid i sekunder.

Brug tokenen. Sæt den i Authorization-headeren: Authorization: Bearer <access_token>. Kun tre operationer klarer sig uden: GetVersion, AuthenticateClient og RevokeToken.

Når den udløber. HTTP 401 betyder at tokenen mangler, er ugyldig eller er udløbet. En token du ikke længere skal bruge, trækkes tilbage med RevokeToken. Skemaerne står i referencen: AuthenticationClientCredentialsRequestBody og AuthenticationClientResponseBody.

Fælles regler for alle kald

Reglerne står én gang i spec’en. Den delte kontrakt — parametre og fejlsvar som næsten alle operationer deler — står på versionsoversigten.

  • version (query, valgfri, på næsten alle operationer) — den API-version klienten forventer. Understøtter provideren den ikke, svarer den med fejlkode 600.
  • ui_language (query, valgfri, på de operationer der angiver den) — det sprog provideren returnerer tekster i. Koderne følger MARC-sproglisten.
  • URL- og query-parametre forventes URL-encodede. Et id med komma i en kommasepareret liste encodes derfor til %2C, mens kommaet mellem id’erne står som det er.
  • Datoer og tidspunkter følger RFC 3339. Et tidspunkt skrives som date-time med stort T og eksplicit tidszone — spec’en antager ingen. En ren dato skrives YYYY-MM-DD.
  • Svar bør ikke indeholde HTML, medmindre operationen udtrykkeligt siger det.
  • Svar der er et map over de id’er du sendte, indeholder kun dem provideren kender. Ukendte id’er udelades; er alle ukendte, er svaret et tomt map.

Fejl

Et fejlsvar (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 tal, og den fulde liste står i skemaet ErrorCode. De tre du møder først:

  • 500 — systemfejl hos provideren.
  • 600 — den version du bad om, understøttes ikke.
  • 10001 — operationen er slået fra hos denne provider.

Resten er domænespecifikke — fx 100023 for et ukendt patronId og 102001 for et ukendt lån — og står alle i ErrorCode; flere operationer beskriver dem de kan give.

HTTP-koderne 400, 401, 404 og 429 er delte svar og beskrives på versionsoversigten. 401 findes i to udgaver: en token der mangler, er ugyldig eller udløbet, og et mislykket klient-login på AuthenticateClient. Et forkert låner-login har sin egen fejlkode, 100001. 429 betyder at provideren begrænser antallet af kald — den er erklæret på Checkin, Checkout og ChangePatronCredential; svaret bør angive i Retry-After hvor mange sekunder der skal gå, og låneren skal se »prøv igen senere«, ikke en fejl i det de har sendt.

Når bibliotekssystemet kalder tjenesten

Trafikken går også den anden vej. Det sker gennem Vendor API'et, og den del implementerer tjenesten selv.

Implementerer du Provider API'et

Så er du provideren. Ud over operationerne beskriver spec'en fem ting du skal tage stilling til — de to sidste er anbefalinger fra dens sikkerhedsafsnit.

  1. Token-endpointet er dit

    Spec'en siger at du bør implementere POST /authentication/oauth2/token og udstede tokens mod client credentials. Spec'en anbefaler en JWT, fordi den kan bruges hvis en del af API'et — fx søgningen — overlades til en tredjepart.

  2. Du afgør hvordan kaldere kendes

    Spec'en nævner to måder: en base-URL pr. bibliotek og credentials pr. leverandør, eller én base-URL hvor credentials afgør begge dele.

  3. Funktioner kan slås til og fra

    GetConfiguration fortæller tjenesten hvad der er slået til; før udlån og aflevering skal tjenesten tjekke den. Fejlkode 10001 betyder at en operation er slået fra.

  4. Et UUID som patronId

    Spec'en anbefaler stærkt et UUID — og, bruger systemet heltal som låner-id, at lægge et UUID ved siden af og kun bruge det i PLAS.

  5. Begræns loginforsøg

    Rate limiting pr. låner-identifikator på POST /patron/authentication og POST /patron/authentication/no-password, og pr. låner når credentials nulstilles eller ændres. Ved ændring af credentials bør grænsen svare med 429.

Næste skridt