Documentation

# uranashel API versioning & deprecation policy

What we promise about changing the uranashel API, and how you will hear about it before anything breaks.

## 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`](https://uranashel.com/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](https://www.rfc-editor.org/rfc/rfc9745), 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](https://www.rfc-editor.org/rfc/rfc8594), 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](mailto: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](https://uranashel.com/index.html) and the [developer portal](https://uranashel.com/developers/).

---

uranashel · [Home](https://uranashel.com/) · [Apps](https://uranashel.com/apps.html) · [Lab](https://uranashel.com/lab.html) · [About](https://uranashel.com/about.html) · [Blog](https://uranashel.com/blog/) · [Developers](https://uranashel.com/developers/) · [API docs](https://uranashel.com/docs/) · [Privacy](https://uranashel.com/privacy.html)

Machine-readable: [llms.txt](https://uranashel.com/llms.txt) · [sitemap.xml](https://uranashel.com/sitemap.xml) · [openapi.json](https://uranashel.com/openapi.json) · [API](https://uranashel.com/api/v1/)