English
English Norsk Dansk

Choose language

English Norsk Dansk

Get started

View as Markdown The page’s .md file llms.txt All pages, for AI tools Open in ChatGPT Ask questions about the page Open in Claude Ask questions about the page

PLAS connects a library's data sources with the services patrons and staff use. Here you find your place in the model and the way to your first call.

Provider API v0.6.7 Last updated

Three ways in

Which API you work with depends on which end you're building. The specification is the same with every library system that implements it.

  • Provider API · Vendor API

    You build a service

    An app, a website, self-service, an info screen or a staff tool. You call the Provider API, and implement the Vendor API if the service uses single sign-on or events.

    Follow the four steps

  • Provider API

    You supply the system

    The library system implements the Provider API: the operations, the token endpoint and how callers are told apart.

    Implement the API

  • Search API · Content API

    You supply data

    Search or events. The Search API and the Content API are subsets of the Provider API's operations, each with its own specification. The spec itself notes that search, for example, can be handed to a third party.

    See the four APIs

First call in four steps

The steps apply to the Provider API in the version that is in production. The details for each step are in the sections below.

  1. Get access

    The base URL and your client credentials come from the provider — the vendor of the library system, which implements the token endpoint. The spec has no shared base URL.

  2. Check the version

    The call needs no token and returns the version the provider recommends — a first check of the connection before you authenticate.

  3. Get a token

    Send your client credentials and get a Bearer token back. It goes in the Authorization header on the calls that follow.

  4. Make the first call

    The configuration tells you what the library system has switched on — checkout, checkin and which identity providers can be used, for example. Before checkout and checkin, the spec requires the service to find them switched on here.

Not sure which calls your service needs? Features start from what you want to build and list the calls behind each one. The spec says of itself that it is still a work in progress and that fields and structure may change — every version is listed with its OpenAPI file on the API overview, and the changelog says what changed in each.

Base URL

The spec has no servers block. The base URL belongs to the provider, not to PLAS, and is agreed with the provider. Every path in the reference — /version, /patron/{patronId}, /authentication/oauth2/token — is relative to it.

The spec describes two ways a provider can tell its callers apart: a base URL per library with credentials per vendor, so the same service calls different addresses at different libraries, or one base URL for all, with credentials identifying both library and vendor. Don’t assume the base URL is the same from one library to the next, even with the same provider.

Authentication

The Provider API uses OAuth 2.0 with client credentials. One call returns a token, and the token goes on the calls that follow.

Get a token. Send a POST to /authentication/oauth2/token with Content-Type: application/x-www-form-urlencoded and three fields: client_id, client_secret and grant_type with the value client_credentials. The call itself needs no token.

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

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

The response is JSON with three fields — all required:

  • access_token — the token itself. The spec recommends that the provider issues a JWT, so it can be used if part of the API (search, say) is handed to a third party.
  • token_type — always Bearer.
  • expires_in — the token’s lifetime in seconds.

Use the token. Put it in the Authorization header: Authorization: Bearer <access_token>. Only three operations do without: GetVersion, AuthenticateClient and RevokeToken.

When it expires. HTTP 401 means the token is missing, invalid or expired. A token you no longer need is withdrawn with RevokeToken. The schemas are in the reference: AuthenticationClientCredentialsRequestBody and AuthenticationClientResponseBody.

Rules that apply to every call

These rules are stated once in the spec. The shared contract — the parameters and error responses nearly every operation shares — is on the version overview.

  • version (query, optional, on nearly every operation) — the API version the client expects. If the provider doesn’t support it, it responds with error code 600.
  • ui_language (query, optional, on the operations that declare it) — the language the provider returns text in. Codes follow the MARC language list.
  • URL and query parameters are expected to be URL-encoded. An id containing a comma in a comma-separated list is therefore encoded as %2C, while the comma between the ids stays as it is.
  • Dates and times follow RFC 3339. A point in time is a date-time with a capital T and an explicit time zone — the spec assumes none. A plain date is YYYY-MM-DD.
  • Responses should contain no HTML unless the operation explicitly says so.
  • Responses that map the ids you sent contain only those the provider knows. Unknown ids are left out; if all are unknown, the response is an empty map.

Errors

An error response (HTTP 400) is an object with the list errors (Errors); each item has code and info (Error), and the first is the most relevant. The code is a number, and the full list is in the ErrorCode schema. The three you meet first:

  • 500 — system error at the provider.
  • 600 — the version you asked for isn’t supported.
  • 10001 — the operation is disabled at this provider.

The rest are domain-specific — 100023 for an unknown patronId, 102001 for an unknown loan — and are all listed in ErrorCode; several operations describe the ones they can return.

The HTTP codes 400, 401, 404 and 429 are shared responses, described on the version overview. 401 comes in two kinds: a token that is missing, invalid or expired, and a failed client sign-in on AuthenticateClient. A wrong patron sign-in has its own error code, 100001. 429 means the provider is limiting the number of calls — it is declared on Checkin, Checkout and ChangePatronCredential; the response should say in Retry-After how many seconds to wait, and the patron must be shown “try again later”, not an error in what they sent.

When the library system calls the service

Traffic also runs the other way. It goes through the Vendor API, and the service implements that part itself.

Implementing the Provider API

Then you are the provider. Beyond the operations, the spec describes five things you need to decide on — the last two are recommendations from its security section.

  1. The token endpoint is yours

    The spec says you should implement POST /authentication/oauth2/token and issue tokens against client credentials. The spec recommends a JWT, because it can be used if part of the API — search, say — is handed to a third party.

  2. You decide how callers are told apart

    The spec names two ways: a base URL per library with credentials per vendor, or one base URL where the credentials identify both.

  3. Features can be switched on and off

    GetConfiguration tells the service what is switched on; before checkout and checkin the service has to check it. Error code 10001 means an operation is disabled.

  4. A UUID as patronId

    The spec strongly recommends a UUID — and, if the system uses integer patron ids, adding a UUID alongside and using only that in PLAS.

  5. Limit sign-in attempts

    Rate limiting per patron identifier on POST /patron/authentication and POST /patron/authentication/no-password, and per patron when credentials are reset or changed. When credentials are changed, the limit should respond with 429.

Next steps