Breaking changes & versioning

If you're evaluating PropSocket as a long-term dependency, this is the contract you're signing up for: how we version, what counts as a breaking change, and how much warning you get before anything you depend on goes away. The short version — we ship a new version only when the contract breaks, and you get six months and three notification channels before a deprecated thing is removed.

URL versioning

The API is versioned in the path: /v1/…. A new major version (/v2/) ships only when an existing contract breaks — never as a routine cadence. A /v2/ does not mean every endpoint changed; it means at least one did. Endpoints that don't break can be served at both /v1/ and /v2/during the transition, so you migrate endpoint by endpoint rather than all at once.

What triggers a new version

These are backwards-incompatible and will only ever arrive under a new version path:

  • Removing or renaming a response field you already read.
  • Changing the type of an existing field (e.g. string → integer).
  • Changing the meaning of an existing field or enum value.
  • Removing an endpoint.
  • Tightening validation so a request that used to succeed now fails.
  • Changing the error envelope or the pagination envelope shape.

What ships in place, no version bump

Additive changes are not breaking and arrive in the current version at any time. Code defensively so they never surprise you:

  • New optional response fields. Ignore fields you don't recognize — we won't break you for reading them, and new ones will appear.
  • New endpoints.
  • New query parameters (filters, sorts) with sane defaults.
  • New webhook event types (webhooks are on the Scale plan and above). Guard your handler on event.type so a new type is a no-op, not a crash.
  • New enum values on an existing field. Tolerate unknown enum values rather than exhaustively switching on them.
  • Loosened validation.

The deprecation window: six months

When something is deprecated, you get six months between the announcement and the removal. During that window the deprecated surface keeps working unchanged. You'll be told three ways:

  1. A Deprecated entry in the changelog on the release that announces it, and a Removed entry on the release that removes it.
  2. Email to your Organization's admins — on announcement day, again 30 days before removal, and again on removal day.
  3. A Sunset HTTP response header (RFC 8594) on every call to the deprecated endpoint, carrying the removal date.
Sunset header on a deprecated endpoint
HTTP/1.1 200 OK
Sunset: Wed, 11 Nov 2026 00:00:00 GMT
Deprecation: true
Link: <https://docs.propsocket.io/changelog>; rel="deprecation"
X-Request-ID: req_01HX9P3K2N7QZRWY4B8MJ5VCDF

Watch for Sunset in your client and log it — it's the earliest programmatic signal that something you call is on the clock. The full deprecation policy and the live list of what's deprecated are on Deprecations.

Next

See the current — and currently empty — list of deprecations onDeprecations, and subscribe to thechangelog to catch announcements the moment they post.