Skip to content

Versioning & deprecation

IRIS exposes a stable read contract. This document states what is versioned, how a breaking change is shipped, and how long a deprecated version keeps serving before removal.

The per-field schema for any version is the live, interactive OpenAPI (Scalar) reference at /docs — it is generated from the running code and is always current. This page describes the policy; /docs is the authoritative schema. The two are not duplicated.

The /v1 prefix contract

Every endpoint of the read contract lives under a URL version prefix, e.g. https://<iris-host>/v1/brands. The prefix is the contract version: /v1 denotes the first stable major version of the REST contract, and the MCP server exposes the matching tool catalog for the same version.

Within a published version (/v1) we only make backwards-compatible changes:

  • Adding a new endpoint.
  • Adding a new optional request parameter.
  • Adding a new field to a response object.
  • Adding a new value to an open-ended enumeration where the contract already documents that the set may grow.

Integrators should therefore tolerate unknown response fields and not assume the response shape is closed — a tolerant reader keeps working across compatible additions.

Breaking changes ship under a new version

A backwards-incompatible change is never applied in place to /v1. Instead it ships under a new version prefix (/v2, and so on), and /v1 continues to serve unchanged. Breaking changes include, for example:

  • Removing or renaming an endpoint, field, or parameter.
  • Changing the type, units, or meaning of an existing field.
  • Making a previously optional parameter required.
  • Changing default behavior in a way an existing client would observe.

This lets an integrator migrate from /v1 to /v2 on their own schedule rather than being broken by a deploy.

Deprecation window

When a version is superseded, it is deprecated, not immediately removed:

  1. Announcement. The deprecation is announced in the changelog, stating the deprecated version, its successor, and the removal date.
  2. Window. The deprecated version keeps serving for a stated window — at least 90 days from the announcement — so integrators have time to migrate. The window may be extended; it is not shortened below what was announced.
  3. Removal. After the window closes, the deprecated version may be removed. Its removal is recorded in the changelog.

Because IRIS runs on a single box with manual operator onboarding (see the SLA), the operator can also reach integrators directly to coordinate a migration when needed.

Where to watch for changes

  • Changelog — every release, deprecation announcement, and removal.
  • /docs — the live, per-version schema reference.