# 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](/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 `switch` on 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](/reference/suggestions#fetch-a-single-suggestion-by-id) 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 `code` inside the existing error envelope. - A longer or differently worded `description` anywhere 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` | `; 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.