Skip to content

API Versioning

The Partners API uses URL-based versioning to provide a stable integration surface while allowing the API to evolve.

Versioning Scheme

The API version is embedded in the URL path:

$BASE_URL/api/v1/listings/
              ^^
           version

The current version is v1. When a new version is released, it will be available at /api/v2/ while the previous version continues to operate.

When a New Version Is Created

A new API version is created when a change would break existing integrations. Breaking changes include:

  • Removing an endpoint or HTTP method
  • Removing a response field or changing its type
  • Removing or renaming a query parameter
  • Changing the meaning of an existing field (e.g., a field that was a string becoming an integer)
  • Changing authentication or authorization requirements in a way that invalidates existing tokens or scopes
  • Changing error response codes for existing error conditions (e.g., a 400 becoming a 422)
  • Changing the default behavior of an endpoint (e.g., default sort order, default page size)

Non-Breaking Changes (No New Version)

The following changes are considered backward-compatible and will be made to the current version without creating a new one:

  • Adding a new endpoint
  • Adding a new optional query parameter
  • Adding a new field to a response (your client should ignore unknown fields)
  • Adding a new optional field to a request body
  • Adding a new scope
  • Adding a new error code for a previously-unhandled condition
  • Improving error messages (the detail text may change)
  • Performance improvements or bug fixes

Warning

Your integration should be built to tolerate additive changes. Always ignore unknown fields in responses rather than failing on them.

Deprecation Policy

When a new version is released:

  1. Both versions run in parallel for a migration period
  2. Deprecation notice is communicated via email and documented here
  3. Migration guide is provided with a mapping of changes between versions
  4. Sunset date is announced at least 6 months in advance
  5. After the sunset date, the deprecated version returns 410 Gone

Version Lifecycle

Phase Description
Active Fully supported, receives bug fixes and non-breaking enhancements
Deprecated Still operational, but a newer version is available. No new features.
Sunset Decommissioned. Requests return 410 Gone.

The current version, v1, is Active.