API Versioning

DVS uses path-based versioning with a /v1/ prefix on every endpoint. This guarantees backwards compatibility for as long as you use a given major version.

Rules

Additive changes do not bump the version

Adding optional fields to request/response bodies, new error codes, new event types, new query parameters — all backwards-compatible. They land in v1 without breaking your integration.

Breaking changes go to a new path

Renaming or removing fields, changing field types, changing semantics of an existing error code, making a previously-optional field required — those land under /v2/.

Old versions coexist for 6 months

When /v2/ ships, /v1/ continues to work for at least 6 months. We notify all providers in advance via support@osigu.com and post on the Changelog.

Deprecation signals via response headers

During the sunset window, deprecated responses include the standard Deprecation and Sunset headers (RFC 8594). Monitor them in your application logs to know when to migrate.

Path version vs event version

These are independent:

• /v1/ in the URL versions the API contract (request/response shapes).
• event_version: 1 in webhook payloads versions the event schema.

A /v1/ endpoint can emit event_version: 2 events if the event schema evolved without the API itself changing. The current event version is always present in the X-DVS-Event-Version header — check it before parsing.

Detecting deprecation programmatically

HTTP/1.1 200 OK
Deprecation: Sun, 01 Jun 2027 00:00:00 GMT
Sunset: Wed, 01 Dec 2027 00:00:00 GMT
Link: <https://docs.osigu.com/changelog>; rel="deprecation"

If your client receives a Deprecation header, log it and notify your team. Plan migration before the Sunset date.