Skip to content

Versioning & deprecation

Tarno 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://<tarno-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 Tarno 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.

In-place deprecation with an early signal (within /v1)

Besides the /v1 → /v2 path for large breaks, a bounded parameter consolidation within /v1 follows this three-step cycle, to give early notice without breaking anyone on deploy:

  1. Early signal. The deprecated parameter keeps working, but the old → new guide is announced and integrators are warned from day one.
  2. Window. The permissive behavior is kept for the stated window (at least 90 days), with the old → new guide published, to give time to migrate.
  3. Retirement. When the window closes, the deprecated parameter is retired: a retired alias is silently discarded (200) and an out-of-vocabulary value becomes 400 validation_error.

The first application of this cycle was the v1.6 consolidation, now completed: the window closed and the denominacion / fechaDesde / fechaHasta parameters were retired from /v1/brands, with estado as a validated enum. See the v1.6 migration guide.

Where to watch for changes

  • /docs — the live, per-version schema reference.
  • Changelog — every version, with its deprecation and removal announcements.