Versioning and deprecation

Where the API is today

There is no version in the URL and no version header. Endpoints are served at their bare paths — /api/dashboard, not /v1/api/dashboard — and the server does not read a version from the request. That is the state of the interface, stated plainly rather than dressed up as a deliberate versionless design.

One version therefore exists: the one being served. Everything below is the policy that governs how it changes, and it applies from today whether or not a version identifier ever appears in a URL.

What counts as a breaking change

The test is whether a correct existing client stops working. These are breaking, and are governed by the notice guarantee below:

Removing an endpoint, or changing its method or path.
Removing a field from a response, or renaming one.
Changing the type of an existing field, or the units of a numeric one.
Making a previously optional request parameter required, or narrowing what an existing parameter accepts.
Changing the HTTP status class of an existing outcome — a refusal that answered 200 beginning to answer 4xx, for instance.
Removing a reason code, or changing what an existing one means. The code is a contract; its English sentence is not.
Tightening a limit, a quota, or an accepted payload size.
Changing the name, scope, lifetime or format of the session cookie.

What is not breaking

These ship without notice, and a client must tolerate them. If yours cannot, that is the bug to fix first:

Adding a field to a response. Never reject an unrecognised field.
Adding a new endpoint, or a new optional request parameter.
Adding a new reason code. Handle unknown codes by rendering the explanation the server sent, as shown in Errors.
Adding a new value to an existing enumerated field — a further store build stage, a further verdict item type.
Rewording an explanation. Never parse prose; branch on the code.
Changing the ordering of an array where no order was documented.
Raising a limit, or making a refusal into a success.
Fixing a response that contradicted this documentation. Where the server and these pages disagreed, correcting the server is a fix, not a break.

The notice guarantee

This is what FlowFinds Solutions holds itself to.

Change	Minimum notice	How you are told
Breaking change to a documented endpoint	90 days	A dated changelog entry marked Breaking, a migration guide, and email to the address on every account that has called the affected endpoint.
Removal of an endpoint	90 days, then 410 for at least a further 90	As above. After removal the path answers `410 Gone` naming the current route — never 404, which is indistinguishable from a typo.
Removal or redefinition of a `reason` code	90 days	Changelog entry marked Breaking. The code remains served by `GET /api/reasons` for the whole notice period.
Tightening a limit or quota	30 days	Changelog entry, and the new figure visible in `GET /api/usage` only when it takes effect — never before.
Security fix that must break something	As long as is safe, which may be none	Shipped first, documented immediately, with the reason stated. This is the one exception to every period above, and we will say so explicitly rather than quietly reclassifying a break as a fix.
Additive change	None	Changelog entry on the day it ships.

Commitments that go with the guarantee

The notice period starts when the changelog entry is published, not when the decision was taken.
Deprecated is still supported. Until the period expires, a deprecated endpoint keeps working exactly as documented. Deprecation is not a soft removal, and it is not a licence to let something rot.
A breaking change ships with its migration guide, not after it. If we cannot describe the migration, the change is not ready.
The registry stays true throughout. Every reason code the server can emit is declared, and every declared code is reachable — asserted in both directions, so a deprecation cannot leave a code documented but dead, or live but undocumented.
Removal is a 410, not a 404. A gone endpoint says it is gone and names what replaced it, as the retired advertising checkout already does.
We will not silently reinterpret a field. A field whose meaning must change gets a new name; the old one keeps its old meaning until it is removed under the notice above.

If a version prefix is introduced

Should the interface ever carry an explicit version, that introduction is itself governed by this policy: the unprefixed paths would keep working for at least the 90-day period, both would be served during it, and a migration guide would exist on the day the prefix appeared. You would not wake up to a 404.

Writing a client that survives

Ignore fields you do not recognise. Never validate a response as a closed schema.
Branch on reason, and fall back to printing the server’s own explanation for codes you have never seen.
Treat enumerated values as open. A new store build stage should not crash a state machine.
Read limits from GET /api/usage rather than hardcoding the numbers on Rate limits.
Diff GET /api/reasons in CI. It is the cheapest drift detector available to you.

Telling us it went wrong

If a change reached you without the notice this page promises, that is a failure of the policy and we want to know. Write to [email protected] with the date, the endpoint and what changed.

Next: Changelog · Migration guides · Errors