API Versioning

When backwards-incompatible changes are made to the API, a new, dated version is released.

🚧

Base URL Change

For versioned endpoints, the base url will be api.amberdata.com

To set the API version on a specific request, you will have to use the api-version header. (see FAQs)

curl --request https://api.amberdata.com/markets/spot/... \
     --header "x-api-key: UAKHelloCryptoHiAmberdata" \
     --header "api-version: 2023-09-30"

Backwards Compatible Changes

Amberdata considers the following changes to be backwards-compatible

  • Adding new API resources.
  • Adding new optional request parameters to existing API methods.
  • Adding new properties to existing API responses.
  • Changing the order of properties in existing API responses.
  • Changing the length or format of opaque, Amberdata generated strings, such as object IDs, error messages, and other human-readable strings.

📘

What are considered non-opaque strings?

Trading pairs, instruments, asset symbols etc. are not considered opaque. Such strings could only be modified with a new dated version.

Versions

Version NameDescription
2023-09-30Simplified endpoints for Market Data Spot and Futures/Swaps.
v2-legacyAnything endpoint with /api/v2 in the path.

FAQs

  1. What happens if I don't specify a version or I provide an invalid value for api-version?
    1. The API will return responses from the fallback version.
  2. What happens to the current version when a new version is released?
    1. The current version will become the new fallback version and the new version will become the current version. If for example, the current version is 2022-12-31, the fallback version is 2022-08-31 and the new version is 2023-03-31, then 2022-12-31 will become the fallback version and 2023-03-31 will become the current version.
      1. This pattern ensures that there will be no disruption to your existing workflows and that you can upgrade to the new, current version with ample time.
  3. What happens to old fallback version(s)?
    1. Old fallback versions are deprecated after a certain period of time and all requests to those versions will fail.