Versioning

The version is the first part of the path: https://api.border.bot/v1/classify. The current version is v1. URLs without a version (/openapi.json, /docs) always serve the current one.

What can change within a version#

Only additions: new endpoints, new optional request fields, new response fields and new enum values. Write clients that ignore fields they don't know and handle enum values they haven't seen. Anything that would break a working client ships as a new version.

Retiring a version#

When a version is deprecated, its responses carry:

After the sunset date, the version answers 410 version_retired. GET https://api.border.bot/versions lists every version with its status, dates and changes.

Each version has its own OpenAPI 3.1 document at https://api.border.bot/v1/openapi.json.