Versioning and deprecation

This is how we change the Foldr API, and what we promise while we do.

One version, in the path

The API’s major version is part of every address: /api/v1. Nothing else chooses a version (there’s no version header and there are no dated versions).

What may change within v1 at any time

• new endpoints;
• new optional parameters;
• new fields in a response;
• new values in a list of values that the reference marks as open;
• new problem types;
• new optional headers;
• a looser limit;
• a different encoding of cursors, which are opaque (never build or change one);
• a stable id for files and folders, if Foldr ever has one.

So your client should ignore fields it doesn’t recognise, and accept values it doesn’t recognise wherever the reference says a list is open.

What needs a new version

• removing or renaming an endpoint, field or parameter;
• changing a field’s type or meaning;
• making an optional input required;
• validating an existing input more strictly;
• a different status code for an existing condition;
• a changed default;
• a different scope on an existing endpoint;
• changing how pages or ids work;
• changing how paths are written back to you (their case, their Unicode form, the leading /).

Changes like these go into a new major version (/api/v2), or come through the deprecation route below.

Security fixes

A change that closes a security hole may break a client without notice. We’ll say what changed straight afterwards.

How long things last

• A major version is supported for at least 24 months after the next one is generally available.
• A deprecated endpoint keeps working for at least 12 months before its sunset date.
• If you run Foldr on your own server, removal also waits for a major Foldr release, and the release notes of the two releases before it say what’s going, because your server upgrades on your schedule rather than ours.

How you’ll know

• a Deprecation header (RFC 9745) on every response from a deprecated endpoint;
• a Sunset header (RFC 8594) once its date is set;
• a Link header with rel="deprecation" pointing to the notice;
• deprecated: true on the endpoint in the OpenAPI document;
• the document’s changelog (info.x-changelog), with the document’s own version number (info.version), which is separate from the API’s major version.

Beta endpoints

An endpoint marked x-foldr-stability: beta may change with 30 days’ notice and stays off unless your organisation opts in. There are no beta endpoints in v1 today.