# Kom i gang Sist oppdatert 10. september 2026 Kilde: https://plas.redia.dk/no/kom-i-gang/ Det du må vite før det første kallet mot et bibliotekssystem som implementerer PLAS Provider API — og hvor referansen tar over derfra. 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](#forutsetninger) - [Base-URL](#base-url) - [Autentisering](#autentisering) - [Første kall](#første-kall) - [Felles regler for alle kall](#felles-regler-for-alle-kall) - [Feil](#feil) - [Implementerer du API-et selv?](#implementerer-du-api-et-selv) - [Neste skritt](#neste-skritt) ## 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. ```http POST /authentication/oauth2/token Content-Type: application/x-www-form-urlencoded client_id=&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 `. **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](/no/provider/v0.6.5/schemas/#AuthenticationClientCredentialsRequestBody) og [AuthenticationClientResponseBody](/no/provider/v0.6.5/schemas/#AuthenticationClientResponseBody); operasjonen er [AuthenticateClient](/no/provider/v0.6.5/authentication/#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](/no/provider/v0.6.5/version/#GetVersion). Hent deretter et token, og kall den første operasjonen i gruppen produktet ditt trenger — for eksempel [Patron](/no/provider/v0.6.5/patron/) for låntakerdata eller [Holding](/no/provider/v0.6.5/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](/no/provider/v0.6.5/). - **`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](https://www.loc.gov/marc/languages/). - **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](/no/provider/v0.6.5/schemas/#Error)). Koden er et tall, og hele listen står i skjemaet [ErrorCode](/no/provider/v0.6.5/schemas/#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](/no/provider/v0.6.5/). ## 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 - [Versjonsoversikten](/no/provider/v0.6.5/) — den delte kontrakten og alle 21 gruppene. - [Skjemaindeksen](/no/provider/v0.6.5/schemas/) — alle 379 skjemaer, ett nivå dypt. - [API-referansen](/no/apier/) — de fire API-ene, og hvordan de henger sammen.