Versioning and deprecation
Versioning and deprecation
This is the page to read before you commit to the integration. It states what
WeR will and will not do to /v1, and what your client has to do so that those
commitments hold. Everything here applies to every operation in
the reference.
/v1 is additive-only
New fields appear on responses. New operations appear. Nothing is removed from
/v1, and nothing already there changes meaning.
A change that would break a correct client is not made in place. It becomes a
new major version under its own path prefix — /v2 — and /v1 keeps working
until it is deprecated and sunset under the policy below.
This is enforced, not merely intended. Every change to the API contract runs through a breaking-change check on the way in, and a change that trips it cannot merge without an explicit, recorded decision to break.
What WeR asks of you in return: ignore unknown fields
Your client must ignore any field it does not recognise, and any enumeration value it does not recognise. This is a requirement, not advice.
The additive-only rule only protects you if your client tolerates additions. A
client that rejects a response carrying an unfamiliar property, or that throws
on an unfamiliar kind, will break on a routine change that WeR is entitled to
ship without notice — and it will break in production, on a day nobody
scheduled.
Concretely:
- Do not use a strict or closed-world schema validator on responses.
- Do not
switchon an enumeration without a default branch that degrades gracefully. - Do not assert that a response object has exactly the properties you expect.
The contract says the same thing where it matters most: the kind on
a suggestion carries
the note that new kinds may be added and an unrecognised one must be ignored.
What counts as breaking
From your point of view, not WeR's.
Not breaking. These ship without notice, and may already have shipped.
- A new property on a response object.
- A new operation, or a new path.
- A new optional query parameter or request-body property.
- A new value in an enumeration — a new suggestion
kind, a new run status. - A new error
codeinside the existing error envelope. - A longer or differently worded
descriptionanywhere in the contract.
Breaking. These never happen inside /v1.
- Removing a property from a response, or making one that was always present optional.
- Removing an enumeration value you might already be handling.
- Removing an operation, or changing its path.
- Making an optional request parameter required, or adding a new required one.
- Changing a property's type, or the meaning of a value it already carried.
- Removing a documented status code from an operation's responses.
The boundary is: if a correct client that follows the rule above would stop working, it is breaking. Adding something it can ignore is not.
Deprecation and sunset
Nothing under /v1 is deprecated today. This section describes what happens
when something is, so you can build for it now rather than discover it later.
Because /v1 is additive-only, deprecation does not mean an operation has
changed or degraded. It means exactly three things: it still works, a
replacement exists, and it will stop working on a stated date.
The signal
A deprecated operation starts sending three response headers. A non-deprecated operation sends none of them, so their presence is the whole signal — you do not need to poll anything or read a changelog to notice.
| Header | Example | What it says |
|---|---|---|
Deprecation | @1767225600 | When the operation became deprecated |
Sunset | Wed, 01 Jul 2026 00:00:00 GMT | When it stops working |
Link | <https://api.we-r.com/v2/inspiration>; rel="successor-version" | What replaces it |
Note that the two dates are written differently, because their specifications
differ. Deprecation follows RFC 9745 and is a structured-field date: an @
followed by whole seconds since the Unix epoch. Sunset follows RFC 8594 and
is an ordinary HTTP-date. Parse them separately; one parser will not read both.
The Link header follows RFC 5829's successor-version relation. Its target
is the operation you should move to.
The notice period
At least 180 days — six months — separate the deprecation date and the sunset date. That is the floor, not the plan; a widely used operation will get longer.
The clock starts at the Deprecation date, which is when the header first
appears. It does not start when you notice.
What to do with the signal
Log it. A deprecation header on a response is the only warning that arrives on its own, and it arrives on a successful response that your code has no other reason to inspect.
The cheapest thing that works: in whatever wraps your API calls, check for a
Sunset header and raise it through your normal alerting. Six months is
generous only if someone sees it in the first week.
How WeR tells you, beyond the headers
The headers are the mechanism. They are not the only notice.
WeR emails the named technical contact on your account — the one given when your credentials were issued — when an operation you have called is deprecated, and again before its sunset date. So keep that contact current: if the person who received your credentials has left, tell WeR, or the notice goes to an inbox nobody reads.
If your integration calls an operation that is later deprecated, the email and the header say the same thing. If they ever disagree, the header is authoritative, because it comes from the API that is actually serving you.