Skip to main content

​
No path-based versions

The Delogue API does not use path-based version numbers — there is no /v1/... or /v2/.... Instead, the API evolves through additive, backward-compatible changes:
  • New optional fields, query parameters, and endpoints are added freely.
  • An existing field is not renamed or repurposed to mean something new. A genuinely different shape gets a new field or a new endpoint (e.g. a userProfiles endpoint alongside users, if the semantics diverge enough) rather than changing what the existing one returns.
  • Changes are deprecated in documentation, not hidden in code — see Deprecation below.
Only read the fields your integration actually needs from a response. Because the API only adds, new fields can appear alongside the ones you already use without affecting you.
New endpoints are only introduced when truly necessary — the default is to extend what already exists rather than stand up a parallel version of it.

​
When a breaking change is unavoidable

A breaking change — renaming or removing a field, narrowing a type, making an optional parameter required, changing what an enum value means — is avoided by default. When one genuinely can’t be avoided, it follows a managed transition instead of an instant cutover:
  • A transition window — the old and new shapes are supported in parallel for a period, rather than the old one disappearing the moment the new one ships.
  • All known consumers are notified ahead of the change taking effect.
  • A migration guide describes what changed and how to adapt.
  • A deprecation timeline states when the old shape stops being supported.
  • Usage is monitored so the team knows who’s still depending on the old shape before it’s removed.
  • A backward-compatible alias is kept where feasible, to soften the cutover further.

​
Deprecation

A deprecated operation or field keeps working — it’s marked, not removed, until its communicated end date:
  • Its guide page carries a deprecation callout naming what to use instead and, where known, the removal timeline.
  • It’s recorded on the Changelog: once under Deprecated when it’s marked, and again under Removed when it’s actually taken out.
  • A breaking or removed change is always flagged for a human reviewer before it reaches these docs — the description is never silently reworded to match a changed contract.
  • Changelog — the dated record of what was added, changed, deprecated, or removed.
  • Errors & responses — the response envelope, which a version or deprecation change never alters.