API versioning & deprecation policy

Current state

Version	Base URL	Status	Released	Deprecated	Sunset
`v1`	`https://uranashel.com/api/v1/`	Current	2026-08-23	—	—

The same table is machine-readable at /api/v1/versions. Read it there rather than parsing this page.

How versions are numbered

The major version lives in the URL path: /api/v1/. A new major version gets a new path (/api/v2/) and the old one keeps working for the notice period below.

Inside a major version, the contract carries a semantic version reported in the API-Version response header and in meta.apiVersion on every response. Today that is 1.0.0.

Patch (1.0.x) — data updates, corrected descriptions, new examples.
Minor (1.x.0) — new endpoints or new optional fields. Backwards compatible.
Major (2.0.0) — anything that could break a client. Ships at a new path; never in place.

What counts as a compatible change

Within a major version we may, without notice:

Add a new endpoint.
Add a new field to an existing response.
Add a new enum member to a field documented as extensible (platforms, category).
Change the value of data fields — download counts, release dates and post lists change as the studio ships.
Relax a validation rule, or widen a documented type union.

Write your client so unknown fields are ignored rather than fatal, and none of the above will affect you.

What counts as a breaking change

Removing or renaming an endpoint, field or operationId.
Changing the type of an existing field, or removing an enum member.
Changing the response envelope, or the meaning of an existing field.
Adding a required request parameter.
Introducing authentication where there was none.

Breaking changes only ever arrive at a new major path.

Notice period

At least 180 days. From the day a version is announced as deprecated to the day it stops responding, you get a minimum of 180 days. The exact removal date is published up front and never brought forward.

How a deprecation is announced

Four signals fire together, so a client detects the change whether it reads headers, polls JSON or reads the website.

1. `Deprecation` response header

Per RFC 9745, every response from a deprecated version carries the moment deprecation took effect, as an HTTP date:

Deprecation: @1789084800

2. `Sunset` response header

Per RFC 8594, the date the version stops responding:

Sunset: Sat, 21 Feb 2027 00:00:00 GMT

3. `Link` header pointing here

Link: <https://uranashel.com/docs/versioning.html>; rel="deprecation"; type="text/html",
      <https://uranashel.com/api/v2/>; rel="successor-version"

4. `/api/v1/versions` changes state

The status field moves from current to deprecated, and the deprecated and sunset fields stop being null:

{
  "version": "v1",
  "status": "deprecated",
  "deprecated": "2026-08-25",
  "sunset": "2027-02-21",
  "policy": "https://uranashel.com/docs/versioning.html"
}

Detecting deprecation from a client

The cheapest check is a single conditional request against the version list:

curl -sI https://uranashel.com/api/v1/apps | grep -iE '^(deprecation|sunset|api-version):'
curl -s  https://uranashel.com/api/v1/versions | jq '.data[] | select(.status != "current")'

If either produces output, plan a migration. Nothing else about the response changes until the sunset date.

After sunset

A sunset version returns 410 Gone with a problem document naming its successor. It does not silently redirect: a redirect would hand your client a differently-shaped payload without telling it.

Questions

Email uralab95@gmail.com before you build something that depends on an undocumented detail — we would rather document it than break it. See also the API reference and the developer portal.

uranashel API versioning & deprecation policy