The API version is part of the URL path:
https://api.directiq.com/v2/senders
└┬┘
versionAvailable versions
| Version | Path | Status |
|---|---|---|
| v2 | /v2/... | Current. Use it for every new integration. |
| v1 | no prefix, for example /template/get/{id} | Supported. Endpoints are being deprecated as their v2 replacements ship. |
Requests without a version prefix are v1An unversioned path is always v1, never the latest version. To use v2, put
/v2/in the path.
What can change within a version
Within a major version we only make backwards-compatible changes, such as:
- new endpoints;
- new optional request parameters or fields;
- new fields in responses;
- new values in
codeand in status fields.
Make your client ignore response fields it doesn't recognize. Breaking changes, such as removing or renaming a field or changing its type, go into a new major version.
Unsupported versions
A path with a version that doesn't exist, such as /v9/senders, returns 400 with code unsupported_api_version. The api-supported-versions response header lists the versions that do exist.
Theapi-versionheaderEarlier integrations selected a version with an
api-versionheader. The header still works for v1 requests, but you don't need it anymore. The path decides the version.
Deprecation and retirement
When an endpoint is replaced, we deprecate it before we retire it. A deprecated endpoint keeps working and adds these headers to every response:
Deprecation: @1793491200
Sunset: Mon, 01 Nov 2027 00:00:00 GMT
Link: </v2/templates/42>; rel="successor-version"| Header | Meaning |
|---|---|
Deprecation | When the endpoint was deprecated, as a Unix timestamp. |
Sunset | When the endpoint will stop working. |
Link (rel="successor-version") | The endpoint that replaces it. |
An endpoint goes through three stages:
- Deprecated. It works normally and returns the headers above.
- Brownouts. Before the sunset date, we switch it off for short scheduled periods. During a brownout it returns
410with codeendpoint_brownout. - Retired. After the sunset date, it always returns
410with codeendpoint_retired.