Provider API v0.6.7

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

The interface a library system exposes so that services can work with patrons, loans, reservations, holdings and payment.

22 groups · 59 operations · 45 paths · 420 schemas Generated from provider_v0_6_7.yaml · OpenAPI 3.0.0 Download the OpenAPI file

Implemented by: The library system
Called by: The services — apps, websites, self-service and staff tools
Profiles of Provider API: Search API · Content API

The Provider API is the main entry point to PLAS. When a library system implements it, a service that speaks PLAS can work with the library without knowing the system underneath.

It covers what a library does every day: the patron and the patron’s consents, loans and renewals, reservations, fees and payment, holdings and locations, checkout and checkin, searching works and publications, and the library’s events. Each part has its own group in the menu.

How to integrate

Three things need to be in place, in the order you meet them:

The base URL. The specification has no servers block, so the address belongs to the provider and is agreed with it. Don’t assume it is the same from library to library, even with the same provider.
A token. POST /authentication/oauth2/token with client_id, client_secret and grant_type=client_credentials returns a Bearer token, which is sent with the calls that follow. Only GetVersion, AuthenticateClient and RevokeToken work without one.
The version. The client can send the version it expects in the version query parameter. If the provider doesn’t support it, it responds with error code 600.

The way to the first call, with examples, is in Get started.

How it relates to the other APIs

The Search API and the Content API are profiles of the Provider API: each of their operations is also here, with the same operationId, method and path. They can be implemented on their own, so a system can offer search or events without the whole Provider API. If you implement the Provider API, you already have both.

The Vendor API runs the other way: it is what the service itself exposes, so the library system can send events and send the patron back after a login.

Shared across operations

These definitions are shared by the API’s operations. They are documented once here; an operation lists only what is specific to it, plus the codes it can return.

Authentication

BearerAuth · oauth2 · Flow: clientCredentials · Token URL: /authentication/oauth2/token

Parameters

version In query · Version · optional · used by 56 of 59 The version of Open Library the vendor expects to receive, if this version isn't supported by the provider an error code 600 (Unsupported Open Library API version) is returned.
ui_language In query · string · optional · used by 10 of 59 The UI language the provider will return the content in. All ui language codes should be on this list https://www.loc.gov/marc/languages/

Error responses

HttpCode400 Errors · used by 58 of 59 The list of errors.
HttpCode401Bearer No response body. · used by 56 of 59 Bearer token invalid, missing, or expired.
HttpCode404 No response body. · used by 35 of 59 Resource not found.
HttpCode429 No response body. · used by 3 of 59 Too many requests. The provider is rate limiting and did not carry out the request. The response should have a `Retry-After` header saying how many seconds to wait. Show the patron "try again later", not an error about what they sent.
HttpCode401UnauthorizedOAuthLogin No response body. · used by 1 of 59 Unauthorized login.