Skip to main content
Version: Next (unreleased)

Versioning & deprecation

The Datamingle API uses URL-based versioning: /api/integrations/v1/.

API versions​

VersionPath prefixStatusDocs
v1/api/integrations/v1/StableCurrent — you're reading them

Breaking changes ship as a new major version (v2). Non-breaking additions ship inside v1 and are listed in the Changelog.

Stability contract​

Within a major version (v1), the following will not change:

  • Existing endpoint paths
  • Required request field names and types
  • Existing response field names and types (new fields may be added)
  • Existing error code values

The following may change without a new major version:

  • Additive request fields — new optional fields in request bodies
  • Additive response fields — new fields in response bodies
  • New endpoints, new resources
  • New error codes for previously-undocumented edge cases
  • Internal enum additions (e.g. a new status value)

Client guidance​

  • Ignore unknown fields in responses. Decoders that fail on unknown keys will break the day we add a new field.
  • Don't hard-code status enums. Treat unknown statuses as "not one I handle" rather than crashing.
  • Log the full error body, not just the code. The message often carries new context.

Deprecation policy​

When we need to break something, we:

  1. Announce in the Changelog at least 90 days in advance.
  2. Serve the Sunset HTTP header on affected endpoints with the removal date (RFC 8594).
  3. Serve a Deprecation: true header and a Link: ...; rel="deprecation" pointing to the changelog entry.
  4. Keep the old behavior working until the sunset date.

Documentation versions​

The docs site is versioned separately from the API. When we ship a non-breaking revision that changes the published contract (e.g. 1.1), we snapshot the existing docs and continue editing the newer set.

  • Version picker — use the dropdown in the top-right of the navbar to switch between documentation versions.
  • Default — the latest released documentation version is served at the root. Older versions live at /x.y/... paths.
  • Next (unreleased) — the /next/ path shows work-in-progress changes that aren't yet released.

If you're unsure which version matches your integration, use the one that matches the API version you call (v1 → docs 1.x).