Versioning
Pin the API contract with the X-API-Version header and upgrade on your own schedule.
The API is served under the /api/v2 base path. Within v2, the exact
request/response contract is selected per request by the X-API-Version
header, so you can adopt changes field-by-field instead of all at once.
The X-API-Version header
Send the contract version you built against on every request:
GET https://api.flavours.sa/dev/api/v2/productsAPI-TOKEN: <your-key>X-API-Version: 2.3.0| Detail | Value |
|---|---|
| Header | X-API-Version |
| Format | MAJOR.MINOR.PATCH (e.g. 2.3.0) |
| Default when omitted | 2.0.0 |
If you omit the header, the API serves the 2.0.0 contract. If you send a value
that is not a valid MAJOR.MINOR.PATCH string, the server falls back to its
configured default rather than erroring — so always send a well-formed version.
What a version controls
The version selects which fields and defaults you receive within v2 — for
example, whether a product returns the newer product_category_id /
preparation_time fields or the older names. It does not change the base path;
that stays /api/v2. A client pinned to an older version keeps the old shape, so
upgrading is opt-in.
Choosing a version
Pin the newest version you have tested against. Newer versions are backward-compatible within the same major line unless the Changelog marks a change as breaking.
X-API-Version: 2.3.0Upgrade on your own schedule
Because the contract is per-request, you can raise X-API-Version field-by-field
as you adopt new behavior. Read the Changelog — it lists every
change and the version it applies from — then bump the header when your
integration is ready.
The playground version selector
Every endpoint's Try it panel includes an X-API-Version dropdown. Pick a
version there to see how that endpoint's request and response change, and the
generated code samples update to send the matching header.