Versioning
What can change in version 1, how a deprecation is announced and where the OpenAPI document is.
Overview
The version is in the path, /api/v1. Version 1 only grows, so a client written against it today keeps working.
What can change in version 1
We may add an operation, a field on a response, an optional parameter or an enum value, so ignore fields you do not know. We do not remove or rename a field, change a type or make an optional parameter required. A change like that would be a version 2 at a new path.
Deprecation
Before an operation is retired, it is marked deprecated, and its answers carry three headers.
| Header | Meaning |
|---|---|
Deprecation | When the operation was deprecated, as @ and a Unix time in seconds |
Sunset | When the operation stops working, as an HTTP date |
Link | The page that says what replaces it, with rel="deprecation" |
An operation deprecated on 1 January 2027 and retired on 1 July 2027 would answer with these.
deprecation: @1798761600sunset: Thu, 01 Jul 2027 00:00:00 GMTlink: <https://attia.app/docs/api-versioning>; rel="deprecation"While the operation carries those headers, the OpenAPI document marks it deprecated: true. Log those headers in your client so a retirement does not surprise you. No operation in version 1 is deprecated today.
OpenAPI document
The OpenAPI 3.1 description of version 1 is public and needs no key. It lists every operation, parameter and field, and you can generate a client from it.
curl https://attia.app/api/v1/openapi.json