- 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
/meoperations).
See Clients and keys, Scopes, Tokens and DPoP.
Conventions
- Standard methods for CRUD.
GET /{collection}lists andGET /{collection}/{id}reads one.POST /{collection}creates and answers201 Createdwith aLocationheader.PATCH /{collection}/{id}updates withapplication/merge-patch+json(RFC 7396) and nothing else: any otherContent-Typeis415withAccept-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 examplePOST /holds/{id}/cancel. It takes anIdempotency-Keyand answers200with the updated resource. A cancelled hold keeps its record (status: cancelled). - No
DELETEin v1. No v1 operation removes a resource. - Status codes. A missing
Idempotency-Keyis400; a missingIf-Matchis428. A405carriesAllow, andAllowincludesOPTIONS.409means a conflict with the resource's current state,422a 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 codeunknown_field). X-Request-IDis on every response: the server's id for the request. Quote it to support. See Idempotency and request ids.- Language.
Accept-Languagechooses the language ofdetailtexts; 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
- Clients and keys: credential kinds, environments, limits, the developer terms
- Scopes: what each scope allows
- Tokens: lifetimes, refresh, revocation
- DPoP: sender-constrained tokens
- Errors and the problem codes
- API reference: the interactive reference, and Try it and collections
- Pagination
- Idempotency and request ids
- Rate limits
- Versioning
- Members: member resources and member apps
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.