Librarika Hubfor developers Test environment
Menu

Using the API

Idempotency and request ids

Idempotency keys

A network failure can leave you not knowing whether a write happened. An idempotency key lets you retry safely: the server runs the operation once and answers a retry with the stored result.

  • Every POST requires an Idempotency-Key header, verb actions such as POST /holds/{id}/cancel included. Without one the answer is 400 idempotency_key_required. A PATCH accepts one too.
  • Use a new UUID v7 (or v4) for each operation, and the same key for every retry of that operation. A key is 1 to 255 visible ASCII characters.
  • Keys are scoped to your credential (and, for member tokens, to the member), and remembered for 24 hours.
POST /lms/v1/holds/5001/cancel HTTP/1.1
Host: api.librarika.dev.raynux.com
Authorization: Bearer $LIBRARIKA_ACCESS_TOKEN
Idempotency-Key: 01932f6e-8a4b-7c3d-9e2f-5a6b7c8d9e0f

What a repeat with the same key gets:

Situation Answer
The first request finished its stored answer, with Idempotency-Replayed: true; the operation does not run again
The first request is still running 409 idempotency_in_progress with Retry-After: 1
The key was used for a different method, path or body 422 idempotency_key_reused

Only successes and business refusals (409, 422) are stored. A 401, 403, 429 or 5xx is not, so once you fix the token or wait out the limit, a retry with the same key runs the operation.

Request ids

Every response carries X-Request-ID: the server's id for this request, a 26-character ULID. Problems repeat it as request_id. Log it with every call; it is what support needs to find the request.

You may send your own X-Request-ID (up to 64 letters, digits, ., _ or -). The server does not use it as the request's id: the response's X-Request-ID is always the server's ULID. Your value is kept alongside it as client_request_id in the library's audit records, so you can correlate both.