Getting Started
Versioning and Deprecation
How the Rhombus REST API changes over time: new operation versions such as spliceV3, deprecated operations and their replacements, Deprecation and Sunset headers, changes made without a new version, and how to write clients that keep working.
On this page
The Rhombus REST API has a single version. There's no version header and no version in the URL: every operation lives at /api/<service>/<operation>.
New versions of an operation
When an operation has to change in a way that would break existing clients, Rhombus adds a new operation with a version suffix and keeps the old one. For example, spliceV3 sits alongside splice and spliceV2, and getSavedClipsV2 alongside getSavedClips. Use the highest version that exists unless the reference says otherwise.
Deprecated operations
The old operation is then marked deprecated:
- The API Reference labels it Deprecated and, when there is one, links to the replacement. The sidebar hides deprecated operations unless you turn on Show deprecated operations.
- The OpenAPI specification marks it
deprecated: true, so generated clients flag it too.
Deprecated operations keep working, but they get no new features. Move to the replacement when you next work on that part of your integration. If an operation is eventually retired, it answers with "error": true and an errorMsg saying so; see Errors.
Deprecation and Sunset headers
When a way of calling the API is scheduled to stop working, responses to requests that still use it carry two headers:
Deprecation: true
Sunset: Tue, 05 Jan 2027 00:00:00 GMTDeprecation: truemeans the request relied on something deprecated. The request itself still succeeds.Sunsetis the date after which the same request fails with an error.
For example, a partner credential that calls an endpoint outside /api/partner/ without the x-auth-org header gets these headers, with the date above; after that date, the same request is an error. On the event WebSocket, such a connection is refused with 403 PERMISSION_REQUIRED. Send x-auth-org with the UUID of the organization to act in (Scoping a call to a client organization).
Log every response that carries Deprecation, with the operation and the Sunset date, so you find these calls before the date.
Changes without a new version
These changes can appear in the existing API at any time; notable ones are announced in the Changelog:
- New operations.
- New optional fields in requests.
- New fields in responses.
- New values in enums, such as a new alert or event type.
Write clients that tolerate them:
- Ignore response fields you don't use, and don't fail on ones you don't recognize. Most JSON libraries do this by default; strict deserializers (for example Jackson with
FAIL_ON_UNKNOWN_PROPERTIES) need it turned off. - Handle enum values you don't know, for example by logging them and skipping the item, rather than throwing.
- Treat a missing field as null. Fields with null values are left out of responses.
- Don't depend on the order of fields in a response or of items in a list, unless the operation documents an order.