Versioning

The Diversity Sync API is versioned by major version in the URL — every resource endpoint lives under /v1. We add to /v1 freely, but we never make a breaking change to it: those ship as a brand-new major version so your integration keeps working until you choose to move.

Every response echoes the major version it was served by in the Diversity-Sync-Version header, so you can always confirm which contract you're talking to.

Every /v1 response carries the version header

Diversity-Sync-Version: v1

Pin your integration to a major version by keeping /v1 in your base URL. When we publish /v2, your existing /v1 traffic is unaffected — you migrate on your own schedule.

What counts as a breaking change

A change is breaking if a well-behaved client could stop working because of it. We never make these to an existing major version — they ship as a new major (for example /v2), never silently.

  • Name
    Removing a field
    Description

    Dropping a property from a response object, or a parameter from a request.

  • Name
    Renaming a field
    Description

    Changing the name of a response property, request parameter, or object object discriminator.

  • Name
    Changing a type
    Description

    Altering the type or shape of a value — for example a string becoming an object, or a scalar becoming an array.

  • Name
    Tightening a default or constraint
    Description

    Reducing a default limit, narrowing an accepted enum, or making a previously optional parameter required.

  • Name
    Changing error semantics
    Description

    Repurposing an existing error code or type, or changing the HTTP status a known condition returns.

When any of these is necessary, the new behaviour is published under the next major version. The old major continues to serve its original contract.

What ships within /v1

Additive changes are not breaking, and they land in /v1 continuously without a version bump. Your client must tolerate them.

  • Name
    New response fields
    Description

    We may add new properties to existing objects at any time — including new nested objects and new entries in the uniform list envelope.

  • Name
    New endpoints
    Description

    Entirely new resources and routes can appear under /v1.

  • Name
    New optional parameters
    Description

    New optional query or body parameters, and new accepted enum values for forward-looking fields.

  • Name
    New event and error codes
    Description

    New, more specific error code values within an existing type.

Because additive changes are routine, clients must tolerate unknown JSON fields and not break on them. Parse the fields you need, ignore the rest, and never assume an object contains only the properties documented today.

Version-independent endpoints

A few endpoints sit outside the versioned surface and are not prefixed with a major version. They follow their own RFC-defined contracts and won't move when a new major ships.

  • Name
    POST /oauth/token
    Description

    The OAuth2 client-credentials token endpoint. It keeps the RFC 6749 { error, error_description } response shape regardless of API major version.

  • Name
    /.well-known/*
    Description

    Discovery documents (for example OAuth/OpenID metadata) are served at their standardised, version-independent paths.

Deprecations

Today, nothing in /v1 is deprecated. When that changes, we won't remove anything quietly — a field or endpoint that is on its way out will be announced in advance through response headers before it is ever retired in a future major.

A deprecated endpoint includes the Deprecation header set to true, a Sunset header with the HTTP-date after which it may stop working, and a Link header pointing at the migration notes. Watch for these headers in your logging so a deprecation never surprises you.

Deprecation headers

  • Name
    Deprecation
    Type
    boolean
    Description

    true when the endpoint or field is deprecated.

  • Name
    Sunset
    Type
    string
    Description

    An HTTP-date marking the earliest point the deprecated behaviour may be removed.

  • Name
    Link
    Type
    string
    Description

    A link to the relevant migration documentation, with rel="deprecation".

Response headers on a deprecated endpoint

Diversity-Sync-Version: v1
Deprecation: true
Sunset: Wed, 01 Jul 2026 00:00:00 GMT
Link: <https://docs.diversitysync.com/v2/migration>; rel="deprecation"

Writing forward-compatible clients

A few habits keep your integration working across every additive change we make to /v1:

  • Name
    Tolerate unknown fields
    Description

    Deserialize into a permissive shape and ignore properties you don't recognise. Never fail a request because a response had an extra key.

  • Name
    Don't depend on field order or count
    Description

    Read values by name. Don't assume objects contain only today's documented properties, or that list items arrive in a fixed order beyond what's documented.

  • Name
    Treat nullable fields as nullable
    Description

    Nullable scalars are always present and may be null. Handle null explicitly rather than assuming a value is set.

  • Name
    Don't assume gated fields are present
    Description

    Permission-gated fields (for example shift hours) are omitted unless your key holds the required scope. Code for their absence.

  • Name
    Handle unknown enum values gracefully
    Description

    Treat unrecognised status, type, or error code values as a default or "unknown" case instead of crashing.

  • Name
    Paginate by has_more, not by count
    Description

    Iterate while has_more is true, passing the last item's id as starting_after. Don't assume a page size or a total.

  • Name
    Keep /v1 in your base URL
    Description

    Pin to the major version explicitly so a future /v2 never changes your behaviour unexpectedly.

  • Name
    Log the version and Request-Id
    Description

    Record Diversity-Sync-Version and Request-Id from every response, and watch for Deprecation/Sunset headers, so migrations are never a surprise.

Was this page helpful?