Librarika Hubfor developers Test environment
Menu

Librarika Hub · API v1

The Librarika API

The Librarika API lets software you write read a library's catalogue and work with its members, loans and holds. It is part of Librarika Hub, the Librarika developer programme. These pages describe version 1 as it is built.

Base URL
https://api.librarika.dev.raynux.com/lms/v1
Authorization server
https://auth.librarika.dev.raynux.com (OAuth 2.1: client credentials, and authorization code with PKCE)
Format
JSON (snake_case), errors as RFC 9457 problems
Contract
an OpenAPI 3.1 document, published with every release

One library per token

Every credential belongs to exactly one library, and the library comes from the credential, never from the path, a header or a query parameter. Paths carry no library id: GET /library is the credential's library and GET /me the member a member token was issued for. Every collection (/catalog/titles, /members, /holds, …) is that library's. To work with two libraries, hold one credential for each.

Credentials

There are two kinds of credential, and each operation says which it takes:

  • A library credential: an API key, or an OAuth client using client credentials. Registered by a library administrator, it acts for the library (staff operations).
  • A member token: an OAuth authorization-code token. A library member signs in and consents, and the token acts for that member only (the /me operations).

See Clients and keys, Scopes, Tokens and DPoP.

Conventions

  • Standard methods for CRUD. GET /{collection} lists and GET /{collection}/{id} reads one. POST /{collection} creates and answers 201 Created with a Location header. PATCH /{collection}/{id} updates with application/merge-patch+json (RFC 7396) and nothing else: any other Content-Type is 415 with Accept-Patch: application/merge-patch+json.
  • Actions are verbs. An action or state change that is not create, read or update is POST /{collection}/{id}/{verb}, for example POST /holds/{id}/cancel. It takes an Idempotency-Key and answers 200 with the updated resource. A cancelled hold keeps its record (status: cancelled).
  • No DELETE in v1. No v1 operation removes a resource.
  • Status codes. A missing Idempotency-Key is 400; a missing If-Match is 428. A 405 carries Allow, and Allow includes OPTIONS. 409 means a conflict with the resource's current state, 422 a refusal under a library rule. See Errors.
  • Enums are lower-case snake_case (active, on_loan, on_hold_shelf) and open: a new value may appear within v1, so accept values you do not know.
  • Ids are integers; times are UTC RFC 3339, dates YYYY-MM-DD.
  • Unknown query parameters are ignored; unknown body fields are refused (422 validation_failed, field code unknown_field).
  • X-Request-ID is on every response: the server's id for the request. Quote it to support. See Idempotency and request ids.
  • Language. Accept-Language chooses the language of detail texts; data such as titles and names is never translated.

Operations

v1 has 26 operations. "Library" operations take a library credential, "member" operations a member token.

Method and path Credential Scope
GET /library library, member library:read
GET /library/branches library, member branches:read
GET /library/branches/{id} library, member branches:read
GET /catalog/titles library, member catalog:read
GET /catalog/titles/{id} library, member catalog:read (copy status also needs availability:read)
GET /catalog/titles/{id}/availability library, member availability:read
GET /catalog/titles/availability?ids= library, member availability:read
GET /me member member.profile:read
GET /me/loans member member.loans:read
GET /me/loans/{id} member member.loans:read
GET /me/holds member member.holds:read
GET /me/holds/{id} member member.holds:read
POST /me/holds member member.holds:write
POST /me/holds/{id}/cancel member member.holds:write
GET /members library members:read
GET /members/{id} library members:read
POST /members library members:create
PATCH /members/{id} library members:update
POST /members/{id}/activate library members:update
POST /members/{id}/deactivate library members:update
GET /loans library loans:read
GET /loans/{id} library loans:read
GET /holds library holds:read
GET /holds/{id} library holds:read
POST /holds library holds:create
POST /holds/{id}/cancel library holds:cancel

The OpenAPI document is the full reference: parameters, bodies, responses and the problem codes of each operation.

Concepts

Quickstarts for each flow follow once the operations are available in the test environment.

Examples on this site

Examples use the fixture library alpha of the test environment and placeholders such as $LIBRARIKA_API_KEY for credentials. They hold no real library data and no real credentials.