API Version Information and Changelog

The GoodDatas REST API is versioned. This allows GoodData to release new APIs for the purposes of deprecation and end-of-life of old APIs without breaking any existing setup on your side.

The API versioning will not break your existing setup without giving you a chance to adapt the newer API. Versioning is straightforward to implement on your side using the X-GDC-Version custom header. To review the changes, see API Version Changelog.

X-GDC-Version Header

When an API resource changes, the global version increases, and the new version of the updated resource is assigned to the new version number. The X-GDC-Version: {version} header specifying the version of the API is used to return the current version.

The GoodData server selects the API version based on the received X-GDC-Version header. If no header is received, the server returns the oldest (deprecated) API version available. A deprecated API version is any version older than the latest one.

Change the X-GDC-Version header via your preferred HTTP client software.

• If you have set the X-GDC-Version header correctly to the current version, the latest API resource is returned.
• If the X-GDC-Version header has an older version number, the older resource is returned with a deprecation warning and information about the most current version.
• If the version is not specified and the resource is versioned, the oldest version that has not yet reached its end-of-life is served.
• If the version is not specified and the resource is not versioned, the only available version is served.

X-GDC-Deprecated Header

The X-GDC-Deprecated header is added to any returned versioned resource and provides information about deprecation and the end-of-life date.

Example:

End-of-life=’RFC1123 DATE-TIME’; valid-version: INT
X-GDC-DEPRECATED: "End-of-life=Sat, X Nov 20XX 12:00:00 GM; valid-version=2"

Deprecation Dates

Deprecation dates are communicated as a part of the Release Notes and within the returned API resource. Subscribe to the Release Notes for information on API deprecation and end-of-life.

When an existing API resource is updated, the global API version is incremented. Deprecation date headers are added to the original API (into the version to be deprecated). Information about the deprecation is published in the Release Notes when a new API resource is published.

Generally, an updated API resource has an end-of-life date approximately one calendar year after the version update (deprecation). During this period, both versions of the API (current and deprecated) are supported. Upon the end of the deprecation period (end-of-life), the old version of the API is removed and only the new version remains.

API Version Changelog