Librarika Hubfor developers Test environment
Menu

Using the API

Versioning

The version is in the path: /lms/v1. Within v1 the API changes only by adding:

  • new operations;
  • new optional parameters;
  • new response fields;
  • new enum values;
  • new scopes;
  • new problem codes.

Nothing within v1 removes or renames a field, changes a type or a meaning, or makes an optional parameter required. Each release of the contract carries a semantic version in the OpenAPI document's info.version: a minor version for additions.

What your client must do

  • Ignore response fields you do not know. They may appear at any time.
  • Accept enum values you do not know. Every enum is open, for example a new hold status. Handle an unknown value as a safe default, never as an error.
  • Treat an unknown problem code by its HTTP status.
  • Do not depend on the order of fields in a JSON object.

The server works the other way for request bodies: an unknown body field is refused (422 validation_failed, field code unknown_field), so a typo never silently drops data. Unknown query parameters are ignored.

Breaking changes

A breaking change comes as a new major version, /lms/v2, served alongside v1. v1 then stays available for at least 12 months after v2 is generally available. During that time every v1 response carries:

  • Deprecation (RFC 9745): when v1 was deprecated;
  • Sunset (RFC 8594): when v1 will stop answering;
  • Link: <…>; rel="deprecation": the migration notes.

Watch for these headers in your logs; v1 sends none of them today.