Using the API
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.
The version is part of every path: https://api.ranqo.ai/v1. The OpenAPI document 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
nullas missing, never as zero. The reference marks every field that can benull. - Branch on an error's
code, not itstitleordetail. - 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.