Versioning

The version is in the path

Every address starts with /api/v1. A change that would break a working integration gets a new prefix; v1 keeps answering while both exist.

Changes we make inside v1

• New endpoints.
• New optional query parameters.
• New fields on objects, and new keys in meta.
• New values in lists that already grow, such as genres and roles.
• Reworded error messages (codes stay).

What counts as breaking

• Removing or renaming a field, parameter or endpoint.
• Changing a field’s type or meaning.
• Changing an error code or status for the same situation.

Each of these is announced in the changelog before it happens.

Building for it

• Ignore fields you do not know.
• Do not assume a list of keys, such as genres, is complete forever.
• Branch on codes, never on message text.