Search API v0.6.5

View as Markdown The page’s .md file Open in ChatGPT Ask questions about the page Open in Claude Ask questions about the page

The read-only discovery interface. Search and retrieve works, publications, agents and suggestions through one query language.

6 groups · 8 operations · 8 paths · 147 schemas

Generated from search_v0_6_5.yaml · OpenAPI 3.0.0

Implemented by: The library system — or a search service in front of it
Called by: Anything that shows a catalogue — apps, websites, kiosks
Profile of Provider API: 8 of the 54 operations in Provider API

The Search API is the reading side of the catalogue: eight GET operations over works (work), publications (publication), agents (agent) and suggestions (suggestions), plus the configuration that says what the provider supports.

The surface is read-only. No operation writes, and that is why it can stand on its own: a search experience can be built once and moved between library systems without touching the rest of the integration.

How to integrate

Authentication, base URL and the version parameter are the same as in the Provider API — the same POST /authentication/oauth2/token, the same Bearer token. Here the specification also declares two scopes, read and write, where the Provider API declares none.

Start with GET /configuration/search. It says which fields and operators the provider actually supports, and reading that is cheaper than guessing.

How it relates to the Provider API

The Search API is a profile of the Provider API: all eight operations are there too, with the same operationId, method and path. The difference is not the content but the scope — a vendor can implement search alone without implementing patrons, loans and holdings.

If you are building against a library system that already has the whole Provider API, you can call these operations in either place. Use this reference when search is all that is in play; it is shorter to read.

Shared across operations

These definitions are referenced by many 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 7 of 8 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 6 of 8 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 7 of 8 The list of errors.
HttpCode401Bearer No response body. · used by 7 of 8 Bearer token invalid, missing, or expired.
HttpCode404 No response body. · used by 6 of 8 Resource not found.
HttpCode401UnauthorizedOAuthLogin No response body. · used by 0 of 8 Unauthorized login.