BuyWhere
← Back to documentation

versioning

Versioning

This page defines how BuyWhere versions the public API, communicates change, and expects developers to migrate.

Version strategy

BuyWhere versions the public API in the URL path.

Examples:

  • /v1/search
  • /v1/products/{product_id}
  • /v1/deals

Rules

  • A major version in the path represents a compatibility boundary.
  • Non-breaking improvements can ship within the same major version.
  • Breaking changes require a new major version such as /v2.
  • SDK versions may move independently of the API version.

What counts as a breaking change

A change is breaking if a reasonable existing client can fail or behave incorrectly without code changes.

Examples:

  • removing an endpoint
  • removing or renaming a response field
  • changing field types or meanings
  • making an optional parameter required
  • changing auth requirements
  • changing default behavior in a way that alters results materially

Examples that are usually non-breaking:

  • adding new optional response fields
  • adding new endpoints
  • improving ranking or performance without changing the response contract
  • expanding enum values where clients are expected to handle unknown values safely

Deprecation policy

BuyWhere should deprecate before removing any public API behavior that external developers or agents may depend on.

Minimum policy

  • Announce the deprecation in the changelog
  • Mark the deprecated behavior in docs
  • Provide a replacement path
  • Include a target removal version or date when known
  • Keep the deprecated behavior available for a reasonable migration window unless there is a security or abuse reason not to

Migration guidance policy

When a change requires client updates, the docs must include:

  • what changed
  • who is affected
  • what to update
  • example before/after behavior
  • deadline or target version if the old behavior will be removed

Current public API posture

Current major version

  • v1

Current support assumption

  • v1 is the active public contract
  • future changes inside v1 should remain backward-compatible where possible
  • any true contract break should trigger a new major version instead of silent drift

Versioning examples

Non-breaking change inside v1

  • add a new optional filter to GET /v1/search
  • add a new optional field to product responses
  • improve ranking quality without changing the envelope

Result:

  • stays in v1
  • note it in the changelog under Added or Changed

Breaking change requiring v2

  • rename buy_url to another field name
  • remove a response field clients already rely on
  • replace an auth header contract

Result:

  • introduce /v2
  • document migration from v1 to v2
  • keep v1 available during the deprecation window when feasible

Migration guide template

Use this structure when BuyWhere introduces a breaking or materially disruptive change:

Summary

  • what changed
  • effective date or target version

Who is affected

  • direct API clients
  • SDK users
  • agent integrations

Required action

  • exact client update needed

Before

{
  "example": "old shape"
}

After

{
  "example": "new shape"
}

Rollout notes

  • deprecation window
  • fallback behavior
  • support contact or escalation path

Release process expectation

For each release, BuyWhere should update:

  • Changelog
  • versioning notes if policy changes
  • OpenAPI examples if contracts changed
  • migration guidance when affected

Related docs