Versioning & deprecation

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

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.

How you'll learn about changes

• The changelog is the source of truth. Watch the page or subscribe to the RSS feed.
• Deprecation headers arrive in responses well before the change.
• Breaking changes to v1 would ship as v2, with v1 kept in parallel for at least 12 months. We have no plans to introduce v2 in the current roadmap.

What "v1" covers

Path prefix	Stability
/api/integrations/v1/	Stable
Internal endpoints elsewhere	Not public — do not consume even if reachable