Skip to content

Versioning

There is no version in the path, and what to read when you need to know what you are calling.

There is no version in the path, no version header, and no versioned media type. Do not build /v1/ into a client — there is no /v1/, and adding one later would be a new address rather than a promise kept.

https://lateano.com/api/pages        ← this is the address
https://lateano.com/api/v1/pages     ← this 404s, and always has

What you can pin to instead

/version.json says which commit and which corpus these bytes were built from.

curl -sS https://lateano.com/version.json
{ "commit": "…", "content": "…" }

Two stamps rather than one, because either can move alone: a merge moves the commit and a publish moves the corpus. A client that saw a different answer than it expected is talking to a different deployment, and this is how it finds out.

Neither is a version you can request. There is one deployment at a time and it serves what it serves. What this gives you is the ability to say precisely which one you observed — which is what you actually need when reporting that something changed.

The number in the OpenAPI document is not the API’s version

/api/openapi.json carries info.version: "1.0.0". That field is not what it looks like. OpenAPI 3.1.1 § 4.8.2 says it is “the version of the OpenAPI Document (which is distinct from the OpenAPI Specification version or the version of the API being described or the version of the OpenAPI Description)”.

The document is assembled in memory on every build from the route table, so it has no separately meaningful version of its own. The constant says the true thing: this document is not separately versioned. If you want to know what you are talking to, read /version.json.

What this API promises about changing

Not much, honestly, and saying so is better than implying a policy that does not exist.

  • A resource that exists will not silently start meaning something else.
  • A refusal will stay a problem document with a resolving type.
  • The list envelope is shared by every list resource, so it changes for all of them or none.

Beyond that: this is a personal site, there is no deprecation window, and there are no consumers on contracts. Build a client that reads what it needs and ignores what it does not, and check /version.json when something surprises you.

The documentation itself is not versioned either. These pages describe the deployment currently serving them.

---
title: "Versioning"
description: "There is no version in the path, and what to read when you need to know what you are calling."
url: "https://lateano.com/developers/api/versioning"
author: "Colin Lateano"
---

# Versioning

There is no version in the path, and what to read when you need to know what you are calling.

**There is no version in the path, no version header, and no versioned media
type.** Do not build `/v1/` into a client — there is no `/v1/`, and adding one
later would be a new address rather than a promise kept.

```
https://lateano.com/api/pages        ← this is the address
https://lateano.com/api/v1/pages     ← this 404s, and always has
```

## What you can pin to instead

`/version.json` says which commit and which corpus these bytes were built from.

```sh
curl -sS https://lateano.com/version.json
```

```json
{ "commit": "…", "content": "…" }
```

Two stamps rather than one, because either can move alone: a merge moves the
commit and a publish moves the corpus. A client that saw a different answer than
it expected is talking to a different deployment, and this is how it finds out.

Neither is a version you can _request_. There is one deployment at a time and it
serves what it serves. What this gives you is the ability to say precisely which
one you observed — which is what you actually need when reporting that something
changed.

## The number in the OpenAPI document is not the API's version

`/api/openapi.json` carries `info.version: "1.0.0"`. **That field is not what it
looks like.** OpenAPI 3.1.1 § 4.8.2 says it is "the version of the OpenAPI
Document (which is distinct from the OpenAPI Specification version **or the
version of the API being described** or the version of the OpenAPI
Description)".

The document is assembled in memory on every build from the route table, so it
has no separately meaningful version of its own. The constant says the true
thing: this document is not separately versioned. If you want to know what you
are talking to, read `/version.json`.

## What this API promises about changing

Not much, honestly, and saying so is better than implying a policy that does not
exist.

- A resource that exists will not silently start meaning something else.
- A refusal will stay a problem document with a resolving `type`.
- The [list envelope](/developers/api/pagination) is shared by every list
  resource, so it changes for all of them or none.

Beyond that: this is a personal site, there is no deprecation window, and there
are no consumers on contracts. Build a client that reads what it needs and
ignores what it does not, and check `/version.json` when something surprises you.

The documentation itself is not versioned either. These pages describe the
deployment currently serving them.