Tools

The OpenAPI document

The whole surface as one OpenAPI 3.1 document, assembled from the routes themselves on every request. It cannot drift from the API, because it is not a second description of it.

What it is good for

Generating a typed client in your language, so the compiler learns this reference.
Importing the surface into an HTTP client or gateway that reads OpenAPI.
Diffing two fetches of it after a release, which shows you exactly what was added. Nothing is ever repurposed, so a diff is always additions.

Fetching it

The document lives behind the same credential as everything else, at GET /api/v1/openapi.json. These reference pages and the document are built from the same derivation, so the two always agree; whichever is easier to read in the moment is the right one.

Worth knowing

Each operation states the ability it requires in its description; where one honours Idempotency-Key, the header appears among its parameters. The statuses listed per operation are the ones it actually answers rather than a boilerplate seven, and request bodies are derived from the validation itself.

Fetch the document

curl https://titanweather.com/api/v1/openapi.json \
  -H "Authorization: Bearer $TITAN_API_TOKEN" \
  -o titan-weather-openapi.json

Generate a client

# A typed TypeScript client
npx openapi-typescript titan-weather-openapi.json -o titan-weather.d.ts

# Or a full client, in most languages
openapi-generator generate -i titan-weather-openapi.json -g php -o ./titan-weather-php