RaabtaHQ
Versioning

Versioning

How the RaabtaHQ API is versioned: the /v1 path, what counts as an additive change, the X-Request-Id header, and where changes are announced.

The version is in the path

Every endpoint lives under /api/v1. The major version — currently 1 — is the only version there is: no header, no query parameter, no date-stamped variants. A request to /api/v1 today and in a year gets the same contract, extended.

The OpenAPI document reports the same version in info.version and is generated from the same definitions as these pages, so the three cannot drift apart.

What changes without a new version

These are additive and can land at any time. A client that ignores what it does not recognise is unaffected by all of them:

  • New endpoints and new resources.
  • New fields in a response object.
  • New optional request fields and query parameters.
  • New values in an enum field, and new error code and reason strings.
  • Rewording of any human-facing message.

Do not validate strictly against today's shape

A client that rejects a response with an unexpected field, or an enum value it has not seen, will break on an additive change. Parse what you use and ignore the rest.

What would need a new version

  • Removing or renaming a field, an endpoint or a resource.
  • Changing a field's type, or making an optional request field required.
  • Changing the HTTP status a given error code returns.
  • Changing an endpoint's stable id — the operationId in the OpenAPI document — which is also its usage-report id and part of its idempotency hash.

Any of those would ship under a new path prefix with the old one kept running, announced in the changelog well ahead of any removal. None is planned.

X-Request-Id

Every response carries X-Request-Id. Send your own value and it is echoed; omit it and one is generated. It is not a version signal — it is the handle on one request for support and for your own tracing, and it is repeated in every error body as request_id.

Where changes are announced

The API changelog lists every change to the contract, newest first, with the endpoints it touches linked. Anything marked deprecated there keeps working for as long as this version does.