Skip to main content

API Versioning & Deprecation

URL versioning​

Hotel transactional REST endpoints are grouped under a major version in the path, for example:

  • /connect/hotels/v1/availability
  • /connect/hotels/v1/prebooking
  • /connect/hotels/v1/booking

Content API endpoints follow the same pattern under their own base path (e.g. /content/hotels/v1/...).

A new major version (e.g. v2) would be introduced only when incompatible changes require clients to migrate. When that happens, v1 remains available for a published sunset period so integrations can upgrade without a same-day cutover.

Breaking vs non-breaking changes​

Non-breaking (no client change required):

  • New optional request fields
  • New response fields
  • New endpoints
  • Bug fixes that align behavior with documented contracts

Breaking (may require client changes):

  • Removing or renaming fields
  • Changing types or semantics of existing fields
  • Removing endpoints
  • Tightening validation in a way that rejects previously accepted requests

Breaking changes are delivered through a new major API version or through an explicit deprecation window on the current version, documented in the Changelog and, for contracted customers, via agreed channels.

Deprecation policy​

When a field or endpoint is deprecated:

  1. Documentation and the Changelog are updated with the deprecation notice and recommended replacement.
  2. A minimum notice period applies before removal (target: 90 days for public REST surfaces unless a shorter window is required for security or compliance).
  3. After the sunset date, the deprecated item may return 410 Gone or be removed in a new major version.

Exact dates for a given deprecation are always listed in the changelog entry.

OpenAPI specification​

The machine-readable OpenAPI document for the Booking API is published by the aggregator service and used to generate the API Reference. Treat the OpenAPI version field and path prefixes as the source of truth for the documented contract.

GraphQL and MCP​

GraphQL and MCP interfaces may evolve on different cadences. Breaking changes there are communicated through the same changelog and, where applicable, schema migration notes in the GraphQL and MCP sections of this site.

What you should do​

  • Pin integration tests to documented request/response shapes.
  • Subscribe to changelog updates or your account’s release communications.
  • Use X-Request-ID on requests for traceability when discussing behavior with support.