# Versioning and compatibility

The version is the first path segment: every route is under `/v1/`. This page says what that promises, what can change without a new version, and where changes are announced.

## What `/v1` means

- **Routes keep their meaning.** An endpoint that exists under `/v1/` keeps its path, its parameter names, and the meaning of every field in its answer.
- **Responses only grow.** New fields, new endpoints, new platforms, new optional parameters and new error types are added to `/v1` without a new version. Fields are not renamed or removed to make room.
- **Parse defensively.** Ignore fields you do not know. Do not fail on an error `type` you have not seen; branch on the HTTP status first and use the type for detail. See [Errors](https://onekey.dev/docs/errors.md).

## Changes that can happen inside `/v1`

| Change | Why it is safe |
| --- | --- |
| A new field in `data`, `metadata` or `pagination` | You can ignore it. |
| A new endpoint or platform | Nothing you call changes. |
| A new optional parameter with a default that keeps today's behaviour | Calls that do not send it behave as before. |
| A new error `type` | Reached only by a request that could not succeed before. |
| A value correction (a count that was wrong, a date in the wrong zone) | The field keeps its name and type; only the value was wrong. |
| A format correction (a link that was relative becomes absolute, a number that arrived as text arrives as a number) | The documented type in the [unified schema](https://onekey.dev/docs/schema.md) is the one that now holds. |
| An endpoint moves from `beta` to `stable` | See [Data availability](https://onekey.dev/docs/data-availability.md#stable-and-beta). Beta endpoints can change shape when they are verified; that is what beta means. |
| Prices | A price change is shown on the endpoint page and in `GET /v1/platforms`. The price in force at the time of a call is the one in `metadata.credits_charged`. |

## What is not done to a published version

- A field is not removed or renamed.
- A type does not change (a number does not become a string).
- A parameter's meaning does not change, and a required parameter is not added to an existing endpoint.
- A fixed-schema field does not change what it means. Platform-specific data lives under `ext.<name>` precisely so that it can differ per platform without touching the shared fields. See the [unified schema](https://onekey.dev/docs/schema.md).

## Breaking changes

Anything that would break a correct client under the rules above is a breaking change and does not ship inside `/v1`. If one is ever needed it ships as a new version path next to `/v1`, and the change is written up in the [changelog](https://onekey.dev/docs/changelog.md) before the old behaviour is withdrawn.

## How to be safe from it

1. Read only the fields you need, by name, and treat unknown ones as noise.
2. For code that must work across platforms, read only fixed-schema fields. `ext.*` names are stable for the endpoint that returns them, not across endpoints.
3. Treat `null` as unknown. See [Data availability](https://onekey.dev/docs/data-availability.md#honest-nulls).
4. Keep an eye on the [changelog](https://onekey.dev/docs/changelog.md), which lists every user-visible change with its date. The [OpenAPI document](https://onekey.dev/openapi.json) and `GET /v1/platforms` always describe the version you are calling.

## Next

- [Unified schema](https://onekey.dev/docs/schema.md) for what the fixed fields mean.
- [Response format](https://onekey.dev/docs/response-envelope.md) for the envelope.
- [Production checklist](https://onekey.dev/docs/production-checklist.md).