# Versioning

The /v1 prefix, how the Filudi API changes without breaking a client, and where the version of this reference comes from.

Every route starts with `/v1`. The prefix changes only when a route stops answering what it answered before.
Within `/v1` the API grows by addition: a new route, a new optional field in a body, a new field in an answer.
A client that ignores fields it does not know keeps working.

## What a client may rely on

- A field listed as required in a response schema is present. A field marked nullable may be null.
- An enum may gain a value. Treat an unknown value as "other", never as an error. `CategoryIcon` is the usual
  case: hub-core draws nothing for an icon name it does not know yet.
- A route that disappears is announced in the release notes of the platform first and answers 404 afterwards.
- The error body keeps its shape and its codes.

## Where the version comes from

The API is released as `games-api <version>`, the version in `info.version` of `openapi.yaml`. Each reference
page states the version it was generated from, in its first paragraph. The published packages have versions of
their own: `@filudi/game-sdk` and `@filudi/hub-core` on npmjs.com follow semver, with release notes written by
Changesets. Pin them exactly (`pnpm add -E`).

## Development only

`GET`, `PUT` and `HEAD /v1/_local-files/{path}` stand in for the files service on a local API without
`FILES_URL`. They are not part of the API and are not in this reference.