Versioning
LIGR versions each resource, not the whole API. The path holds the version.
GET /rest/v1/matches/{matchId}GET /rest/v2/matches/{matchId}Both versions run at the same time. A resource moves to v2 when its shape changes in a way that would break v1 clients. Resources that have not changed stay on v1 only.
A new resource starts at the current version. It has no older path. For example,
PUT /rest/v2/matches/{matchId}/lineup and every /rest/v2/themes route exist only under v2. A
v2 path does not mean that a v1 path exists.
The REST reference adds (v1) or (v2) to a label only when both versions of that operation exist. The two sit next to each other in the sidebar. Use the higher version for new work. A label without a version has one path only.
What LIGR can change without a new version
Section titled “What LIGR can change without a new version”- A new optional field in a response.
- A new optional query parameter or body field.
- A new endpoint.
- A new enum value in a field that already accepts several values.
Write your client so that an unknown field does not break it.
What needs a new path version
Section titled “What needs a new path version”- A field that is removed or renamed.
- A field whose type changes.
- A required parameter that is added.
- A change in the meaning of an existing field.
Beta endpoints
Section titled “Beta endpoints”Some endpoints ship as beta before their shape is final. Today the Themes and Code graphics
operations under /v2/themes are beta. See Beta status.
A beta endpoint can change in ways that the rules above reserve for a new path version. Each change gets a changelog entry, and a removed or renamed field keeps working for at least 30 days after that entry. A beta endpoint is marked in three places.
| Where | Marker |
|---|---|
| The OpenAPI document | x-beta: "true" on the operation |
| The reference page | A Beta line at the top of the operation |
| Every response | X-Ligr-Beta: true and a Link header with rel="help" |
Deprecation policy
Section titled “Deprecation policy”A deprecated endpoint keeps working for at least 12 months after its changelog entry. While it is deprecated it returns two headers.
| Header | Meaning |
|---|---|
Deprecation | The date the endpoint became deprecated |
Sunset | The date the endpoint stops working |
Watch the changelog for the entry, and read the Sunset header in your client logs.
The specification version
Section titled “The specification version”The OpenAPI document carries its own version in info.version. It is the version of the newest
changelog entry, so the reference, the changelog and the API always show the same
number. Read it at https://api.ligr.live/rest/swagger.json.
/openapi.json holds the same operations as that document, regrouped for this
site. Generate a client from swagger.json. Read /openapi.json to see what this site shows.
The REST reference on this site is generated from that document, so it never drifts from what is deployed.