Coin Metrics API Versioning Policy

The list of currently available versions is available at API documentation home page.

Background

API is versioned using Semantic Versioning.

The API version number convention is major.minor.patch. The notation rules are:

Versioning

Major versions of the API are run in parallel. The choice of what major API version to use is up to the client, although clients are advised to use the highest stable version.

Major versions can be marked as either stable or unstable. As backward incompatible changes can be introduced only in unstable or development major versions, no breakage is expected when using fixed, stable major API versions (and adhering to safety guidelines below).

New major API releases are to be added alongside old major API versions, so clients of old (stable) versions are not affected. Old major API versions may be gradually deprecated and removed, following a (generally long-term) deprecation schedule. This should give clients time to adapt their implementations to the new major version.

Minor and patch releases replace old minor/patch API versions, under the same major version. Old minor/patch API versions become inaccessible following these releases.

Unstable major versions

Recently introduced versions of the API may be explicitly labeled "unstable". Unstable API versions are meant to be fully tested, usable by clients, and have complete documentation. However an unstable API version is not covered by the backward compatibility rules below, and can receive arbitrary changes at any time without any warning. Unstable API versions should be used only for evaluation of new features and it is advised to not use unstable versions in production systems.

New major versions of the API are expected to be marked unstable, and after a period of stabilization and testing become permanently stable.

Development major versions

The newest version of the API may be explicitly labeled "development". Development API versions may receive arbitrary changes at any time and may also have wrong/incomplete implementation, documentation, or other critical issues. Generally development API versions should be completely avoided, as there's no guarantees about how well it works, or whether it works at all.

Backward compatible changes

A change is considered backward compatible when an API client built for an old version of the API still works with the new version. Hence it is important that clients use correct assumptions about what details of the API they can rely on.

Changes considered backward-compatible (can be introduced in minor or patch API version)

These changes can be introduced in minor or patch API versions. The follow the below recommendations to avoid broken integrations:

Changes considered backward-incompatible

These changes can only be introduced in A new major API version, or unstable major API version. It is safe to assume that this will not happen to fixed, stable major API versions.

Emergency changes

Generally changes to the API interface and functionality will follow this policy as outlined above. However breaking changes may still be made without introducing a new major version, if it is needed for continuous operation of Coin Metrics services, for security reasons, or for other reasons, if following this policy is deemed to be infeasible. That may include, but is not limited to, the following: introducing or changing request rate limits, applying specific limits per specific API key, immediate disabling of specific methods or features, etc. Changes also can be made to this policy.

Such emergency changes are expected to be rare exceptions and would be conducted only after care assessment of the impact to clients. In the event of such a change, Coin Metrics would provide as much advance notice as possible.