Versioning & Deprecation Policy

How the Signals v1 API evolves — additive-only changes, what counts as breaking, and how deprecations are signalled.

Overview#

The Signals REST API is versioned in the URL (/api/v1/). Version 1 is governed by a strict additive-only contract: existing behaviour never changes in a way that could break a well-behaved integration. New capabilities are added; nothing is silently taken away.

This policy exists because Signals aims for drop-in compatibility with industry-standard rental management systems. The default shape of every response is a frozen contract — integrations depend on exact field names and structures.

Pre-1.0 status — the guarantee is not yet in force#

Signals has not yet shipped 1.0. Until the 1.0 release, the additive-only guarantee described below is the contract we are building towards, not one that binds us today. While pre-1.0 we will correct genuine defects in the wire contract — including changes this document otherwise classifies as breaking — rather than carry a known-wrong shape into 1.0 and be stuck with it for the life of v1.

Every such correction is still recorded honestly in the changelog with a change_type of changed or removed, never disguised as an addition or a fix. Integrators building against a pre-1.0 branch should pin their version and read the changelog before upgrading.

At 1.0 this section is removed, the changelog gate in tests/Feature/Api/ChangelogApiTest.php is tightened back to additive-only, and everything below becomes binding.

The additive-only guarantee#

From 1.0 onward, within v1, we will only make non-breaking changes. Concretely, the following are considered safe and may ship at any time:

• Adding a new endpoint.
• Adding a new, optional request parameter whose omission preserves existing behaviour (for example ?fields= sparse fieldsets, or the optional Idempotency-Key header).
• Adding a new field to a response body. Clients must ignore unknown fields.
• Adding a new optional response header.
• Adding a new enum value to a field already documented as extensible.
• Adding a new webhook event to the event registry.
• Relaxing a validation rule so that previously-rejected input is accepted.

Because responses only ever gain fields, a client that reads the fields it knows about will continue to work unchanged.

What counts as a breaking change#

The following changes are breaking. From 1.0 onward they will never be made within v1 and would only ever appear behind a new major version (/api/v2/). While pre-1.0 they may still be made to correct a defective contract, and are recorded as changed/removed in the changelog:

• Removing or renaming an endpoint, field, or response key.
• Changing the type of an existing field (for example integer → string).
• Changing the meaning, units, or format of an existing field.
• Adding a new required request parameter, or making an optional one required.
• Tightening a validation rule so previously-valid input is rejected.
• Removing an enum value, or changing an existing one.
• Changing default sort order, pagination defaults, or error response shapes.
• Changing authentication, authorisation, or rate-limit semantics in a way that rejects previously-accepted requests.

The compatibility gate (tests/Feature/Api/Compat) freezes the default response shape of the core resources and fails the build if any of these slip through.

Discovering changes#

Every additive change is recorded in a machine-readable changelog:

GET /api/v1/changelog

Each entry records the date, the affected endpoint(s), the change type, and a human-readable description. Poll it to discover new capabilities programmatically.

Deprecation signalling#

Although nothing in v1 is deprecated today, the API reserves the standard mechanism for signalling that an endpoint will eventually be superseded. When an endpoint is deprecated, its responses carry these headers:

The Deprecation and Sunset headers are CORS-exposed so browser-based clients can read them. A deprecated endpoint continues to function throughout its sunset window — deprecation is a signal, never an immediate removal.