Versioning and change policy
Short version: the API is versioned by URL path only, and there is no formal deprecation policy yet. This page says what we do in practice so you can plan around it, rather than implying guarantees that do not exist.
How the API is versioned
Every endpoint lives under /v1. That is the whole mechanism.
- No version header. Nothing you send changes which version answers.
- No
/v2. There has never been one. - No per-account pinning. Everyone is on the same
/v1at the same time.
SCIM is the one exception, served at /scim/v2 because
RFC 7644 fixes that path. Its v2
is the SCIM spec version, not ours.
What we treat as safe to change without a new version
Adding things. New endpoints, new optional request fields, new response fields, new enum values on a field that already exists.
So write a tolerant client. Ignore response fields you do not recognise rather than failing on them, and do not assume an enum is closed. A client that rejects unknown fields will break on an ordinary Tuesday.
What we treat as breaking
Removing or renaming a field, changing a type, removing an endpoint, tightening validation, or changing the meaning of a status code.
The deprecation policy
We give at least 30 days’ notice before an endpoint stops working, counted from the day the changelog entry publishes, not from the day we decided.
30 and not 90 deliberately. A window we miss once is worse than a shorter one we always keep, and this is the number we can honour today. It goes up, with notice, as the platform settles.
During the notice period a deprecated endpoint keeps working normally and its responses carry:
Deprecation: true
Sunset: Sun, 31 Jan 2027 00:00:00 GMT
Link: <https://developers.lockally.com/changelog/>; rel="deprecation"
Sunset is RFC 8594: the date the
endpoint stops responding. Link points at the entry explaining what to use
instead.
A deprecation always names its replacement. If there is nothing to move to, it is a removal, and removals get the same notice.
Watch for the header, do not rely on reading the changelog. Log a warning
when a response carries Deprecation, and you will find out months before a
customer does.
Breaking changes are flagged in the changelog
Entries carry a badge:
- Breaking, something that worked stopped working or changed shape.
- Deprecation, something still works but will be removed, with the replacement named in the entry.
Everything else is additive.
SDK versioning is separate
The clients version independently of the API, with their own semver. They are generated from one spec, so an SDK release can be breaking while the HTTP API is unchanged.
0.3.0 is the example. Every method was renamed, because 80 operations
had no operationId and the generator had been deriving names from routes.
Nothing about the HTTP API moved. If you call the API directly you were
unaffected; if you used an SDK you had to rename every call.
So pin your SDK version and read its changelog entry before upgrading, and do not infer an API change from an SDK one.
What is promised today
/v1 will not be removed or broken without at least 30 days’ notice, in the
changelog and in the headers above. Additive changes keep arriving without
warning, so write a tolerant client.
Anything stronger than that is not promised, and this page will say so rather than imply otherwise.