API Stability, Versioning, and Deprecation
Before building on the RealityConnect API long-term, understand which parts of the surface are stable, how experimental operations are marked, and what to expect across upgrades.
Experimental operations
Section titled “Experimental operations”Some operations in the API reference carry an experimental stability marker. Look for x-scalar-stability: experimental on an operation in the OpenAPI document (visible as a stability badge in the rendered API reference) to identify them. This is kept in sync with the API automatically, so check there rather than relying on a fixed list here.
Experimental operations are real and callable (not disabled or preview-only), but their paths, parameters, payloads, responses, or availability may change without the same stability guarantees as the rest of the API. See Getting Started: Experimental endpoints for how to work with them.
When an experimental operation stabilizes, that’s called out in the Release Notes.
Breaking vs. non-breaking changes
Section titled “Breaking vs. non-breaking changes”| Change | Breaking? | Why |
|---|---|---|
| New optional request parameter | No | Existing requests keep working unchanged |
| New response field | No | Existing consumers that read known fields are unaffected; parse responses tolerantly and ignore unrecognized fields |
| New enum value added to an existing field | No | Treat enum fields as open sets and handle unrecognized values gracefully, rather than exhaustively matching every known value |
| Existing field removed or renamed | Yes | Breaks any consumer reading that field |
| Existing field’s type or meaning changed | Yes | Breaks any consumer relying on the previous shape |
| Required parameter added to an existing operation | Yes | Breaks existing requests that don’t send it |
| Endpoint path or HTTP method changed | Yes | Breaks existing requests outright |
| An experimental operation’s contract changes | No (by design) | Experimental operations are explicitly exempt from the stability contract; see above |
Deprecation policy
Section titled “Deprecation policy”Before a stable operation is removed, it is deprecated with a sunset date. The API reference marks the operation as deprecated, and its OpenAPI definition carries deprecated: true and the sunset date in x-sunset (YYYY-MM-DD).
- A deprecated stable operation keeps working until its sunset date, and may be removed on or after that date.
- There is no fixed minimum notice period: the sunset date of each deprecation is its notice.
- A deprecated request parameter with a sunset date follows the same rule.
- Some query parameters are renamed with a backward-compatible alias: the old name keeps working alongside the new one.
- Experimental operations are exempt: they can be deprecated without a sunset date, and changed or removed without notice, per Experimental operations.
What’s next?
Section titled “What’s next?”- See the API reference for the current stability marker, request and response schema per operation.
- See Getting Started for the security model and how to choose an OAuth flow.