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.