Skip to main content

OpenAPI specification

The OpenAPI specification is the source of truth for the API. The reference pages on this site are generated from it, and changes to the spec are reviewed alongside the implementation.

Download​

FormatURL
YAML/openapi.yaml
JSON/openapi.json

Both files contain the same specification. It's written in OpenAPI 3.1, which is compatible with JSON Schema 2020-12.

Make sure your generator supports OpenAPI 3.1. Some older tools only support 3.0.

Why the docs are generated​

Keeping field tables and the implementation in sync by hand doesn't work for long. Eventually, the two drift apart.

Instead, the reference documentation is generated from the specification at build time. The build also runs the spec through our linter, so a broken or invalid specification won't make it into the docs.

The rule is simple: if a field appears in the docs, it exists in the specification. If it isn't in the specification, it won't appear in the docs.

Generating a client​

AletaPlanet doesn't provide server-side client libraries. The API is plain HTTP with bearer-token authentication, so you can use any HTTP client you like.

If you want a typed client, generating one from the OpenAPI specification is the recommended approach:

# Using openapi-generator
openapi-generator-cli generate \
  -i https://developer.aletaplanet.com/openapi.yaml \
  -g typescript-fetch \
  -o ./aleta-client

A generated client is a good starting point, but there are two things it won't handle for you reliably:

  • Idempotency keys. Generated clients usually don't know about the retry-with-the-same-key pattern. You'll need to add that logic yourself.
  • Money types. Most generators map integers to the language's default numeric type. Make sure amounts stay integers and don't get mapped to floating-point types. See timestamps and money.

Pinning​

The specification at the URL above always tracks the current release.

For reproducible builds, download the specification and commit it to your repository instead of fetching it during the build. Additive changes are released continuously, so generating a client from the live URL can change your generated code without any change on your side.

Validating​

The specification is linted in CI using rules that enforce the conventions used throughout the API, including snake_case fields, _at timestamp suffixes, and ID prefix patterns.

If you extend or fork the specification, running the same lint rules is the quickest way to keep your changes consistent with the rest of the API.

Last updated on