# API versioning

> How the Ranqo API is versioned, which changes happen within a version, and how to write a client that keeps working as the API grows.

Source: https://ranqo.ai/docs/api/versioning

The version is part of every path: `https://api.ranqo.ai/v1`. The [OpenAPI document](https://ranqo.ai/docs/openapi.json) describes the current version, and its `info.version` is 1.0.0.

## Changes within a version

Within `v1`, endpoints and response fields are added, never removed or renamed, and a field keeps its meaning. A change that would break a working client, such as removing a field or changing what one means, gets a new version in the path.

## Writing a client that keeps working

- Ignore response fields you do not know. New ones can appear at any time.
- Read a value that can be `null` as missing, never as zero. The reference marks every field that can be `null`.
- Branch on an error's `code`, not its `title` or `detail`.
- Send only the query parameters an endpoint takes: an unknown one is refused with `unknown_parameter`.
- Allow for new values in fields that name an engine, a category or a state.