Versioning and deprecation

Your app should never break because we shipped something. This is the promise, and how you will hear about anything that could affect you.

The version is in the URL

Everything lives under /api/v1. v1 is current and is not deprecated. A wide redesign would be a new /api/v2 running beside v1 for at least a year, with a migration guide.

What may change without notice

Additive changes, which a well-behaved client never notices:

  • new endpoints, new optional request fields and query parameters;
  • new fields in responses (ignore fields you do not know), new webhook events;
  • new error.code values on statuses an endpoint already returns;
  • wording of error.message (branch on error.code, never on the message).

What never changes without notice

Removing or renaming anything; changing a field's type, unit, sign or meaning; making an optional field required; refusing input we used to accept; changing a status code or error.code; changing pagination or order; requiring a new scope or role. These go through deprecation:

  1. The new way ships beside the old one. Both work.
  2. The old one is announced on the changelog with the endpoints it affects, what to use instead and a sunset date at least 90 days away — 180 days for anything that moves money or touches authentication.
  3. Every response from it says so, from the day it is announced: 
    Deprecation: @1793318400
Sunset: Wed, 28 Jan 2027 00:00:00 GMT
Link: <https://hasslefreebooks.com/developers/changelog#2026-10-30-example>; rel="deprecation"; type="text/html"
    (RFC 9745 and RFC 8594. Log a warning when you see them; the SDKs do.)
  4. We email the developers it affects — those whose apps or API keys called the endpoint in the last 90 days — with exactly which of their calls are affected. Your app's page in the console lists them too.
  5. It is removed only after the sunset date, and only once our logs show nobody still calls it or every remaining caller has been told twice.

The one exception

A security hole is closed at once. It still gets a changelog entry (type security) saying what changed and why, and the developers affected are told.

Staying informed

  • The changelog lists every change a client can notice.
  • Keep the email on your developer account current; it is where notices go.
  • The OpenAPI document (/api/v1/openapi) and the SDKs are regenerated with every change.

Some deprecations name an opt-in you can send today, as a Prefer request header (RFC 7240). For example, signup's Prefer: signup=neutral. Requests that send it already get the new behaviour and carry no Deprecation headers, and the response confirms with Preference-Applied.