Librarika Hubfor developers Test environment
Menu

Using the API

Members

Two kinds of integration work with members: member apps, which act for one member with a member token (/me), and staff integrations such as a student-information-system sync, which act for the library with a library credential (/members, /loans, /holds).

Member apps (/me)

A member token is issued after the member signs in to their library and consents to the app's scopes (see Tokens).

  • GET /me answers the member and their library: member {id, member_no, name, status} and library {id, name}. Member tokens carry no email, phone or address.
  • GET /me/loans and GET /me/loans/{id} are the member's current loans; v1 exposes no loan history, and a returned loan is 404.
  • GET /me/holds lists the member's waiting, ready and suspended holds; GET /me/holds/{id} reads one in any status.
  • POST /me/holds places a hold (201 with Location); POST /me/holds/{id}/cancel cancels one (200 with the hold, status: cancelled). Both need member.holds:write and an Idempotency-Key.

Members see and revoke the apps they connected on their library's "Connected apps" page.

When the library blocks a member

If the library makes a member inactive or stops them signing in, the member loses every app connection at that app's next refresh (the refresh answers invalid_grant); until then their calls are 403 member_access_required. If the library unblocks them later, nothing comes back on its own: the member consents again in each app. Library administrators should know this before blocking a member for a short time, and member apps should send the member through authorization again when a refresh fails this way.

Single sign-on members

Members who sign in to their library only through single sign-on (SAML or Google) get read scopes only for now: a write scope needs a sign-in that Librarika verified itself, within the last 15 minutes. An app that places holds should tell such members that holds must be placed in the library's own catalogue for now.

Staff integrations (/members)

GET /members and GET /members/{id} need members:read; writes need members:create or members:update on a confidential OAuth client with private_key_jwt.

A Member has id, member_no, name, email, phone, member_group {id, name}, status, external_ref (your own id for the member) and updated_at.

Status

status is active, inactive or banned (lower-case, and open: accept a value you do not know).

  • POST /members/{id}/activate and POST /members/{id}/deactivate change it (members:update, an Idempotency-Key, 200 with the Member and its new ETag). A member already in the target state answers 200 unchanged.
  • banned is read-only in v1: no operation sets or clears it, and activating or deactivating a banned member is 409 member_banned.
  • PATCH cannot change status: sending it is 422 validation_failed with field code unknown_field on /status.
  • Deactivating a member ends their app connections at the next refresh, as above.

Creating

POST /members with name and optionally email, phone, member_no (otherwise the library's numbering assigns one), member_group_id, external_ref and invite (send the library's invitation email; it needs email). It answers 201 with Location: /lms/v1/members/{id} and needs an Idempotency-Key.

POST /lms/v1/members HTTP/1.1
Host: api.librarika.dev.raynux.com
Authorization: Bearer $LIBRARIKA_ACCESS_TOKEN
Content-Type: application/json
Idempotency-Key: 01932f6e-8a4b-7c3d-9e2f-5a6b7c8d9e0f

{"name": "Alpha Fixture Member", "member_no": "A-0001", "external_ref": "sis-0001"}

A member_no or email already held by another member is 409 member_no_taken or 409 email_taken: for a sync, look the member up by external_ref instead of creating it again.

Updating

PATCH /members/{id} takes application/merge-patch+json only (RFC 7396: send only the fields to change, null clears email, phone, external_ref or member_group_id); any other media type is 415 with Accept-Patch. It needs If-Match with the ETag you read: without one it is 428 precondition_required, with a stale one 412 precondition_failed. This keeps two integrations from overwriting each other.

PATCH /lms/v1/members/1001 HTTP/1.1
Host: api.librarika.dev.raynux.com
Authorization: Bearer $LIBRARIKA_ACCESS_TOKEN
Content-Type: application/merge-patch+json
If-Match: "$ETAG_FROM_GET"

{"phone": null, "external_ref": "sis-0001"}

Syncing

Read changes with GET /members?updated_since=… and the cursor until next_cursor is null, then keep the highest updated_at for the next run (see Pagination). Staff loans and holds (GET /loans, GET /holds) carry the member's id and member_no, never names or contact details; an integration that needs those also holds members:read.