Skip to main content

​
API Versioning Strategy

​
Current State

The Rhombus API is currently unversioned — there is a single version of all endpoints ("version": "1.0" in the OpenAPI spec). All consumers use the same API surface at https://api2.rhombussystems.com. No versioning mechanism is needed at this time.

​
When to Introduce Versioning

Add versioned documentation when any of the following occur:
  1. Breaking endpoint changes — an existing endpoint’s request/response schema changes in a way that would break existing integrations.
  2. Endpoint removal — a previously documented endpoint is removed from the API.
  3. Authentication changes — the x-auth-scheme / x-auth-apikey header contract changes.
  4. Base URL migration — the API moves from api2.rhombussystems.com to a new host.
Non-breaking additions (new endpoints, new optional fields) do not require versioning.

​
How to Implement (Mintlify)

Mintlify supports version-based navigation via a versions array in docs.json. When the time comes:

​
1. Add versions to docs.json

{
  "versions": ["v2", "v1"],
  "navigation": {
    ...
  }
}
The first version in the array is the default. Users can switch versions via a dropdown in the top navigation.

​
2. Organise content by version

Each version can have its own navigation structure. Shared pages (guides, tutorials) can be reused across versions. Only version-specific API reference pages need separate entries.

​
3. Keep a separate OpenAPI spec per version

api-reference/
  v1/openapi.json   ← current spec (rename)
  v2/openapi.json   ← new version
Update docs.json to point each version’s API Reference to its own spec file.

​
4. Add redirects

When deprecating a version, add redirects in docs.json: 
"redirects": [
  { "source": "/api-reference/v1/:path*", "destination": "/api-reference/v2/:path*" }
]

​
Deprecation Policy

When a version is deprecated:
  1. Add a <Warning> banner to the top of the deprecated version’s pages.
  2. Keep the deprecated version accessible for at least 6 months.
  3. Add an entry to changelog.mdx announcing the deprecation.
  4. Update the update-openapi.yml workflow to fetch both specs if both versions are still served by the API.

​
References