The list of currently available versions is available at API documentation home page.
The API version number convention is major.minor.patch. The notation rules are:
Backward incompatible changes increase the major number.
Backward compatible changes increase the minor number.
Backward compatible bugfixes increase the patch number.
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.
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.
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.
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.
These changes can be introduced in minor or patch API versions. The follow the below recommendations to avoid broken integrations:
Addition of a new API method. Do not rely on absence of specific URL path or API method.
Addition of new constant-named fields to response structures of existing API method. Do not rely on the absence of unknown fields in API response structures.
Addition of new optional request parameter to method, given that its absence has the same meaning as it was before the change. Do not add unsupported request parameters to API calls - they are ignored while unsupported, but may suddenly become "supported".
Making previously mandatory request parameters optional.
Addition of new possible values for enum-typed request parameters of the API method.
Changes in human-friendly strings (i.e. asset/metric names/definitions, error descriptions). Do not make decisions in your code based on human-friendly strings. These strings can be changed for reasons like fixing misspelling or style. Use fields designed to be "stable", e.g. error codes, etc.
Adding/removing/changing available resources: assets, metrics, etc. Availability of specific assets/metrics/etc is not part of the API interface and not covered by this policy. You should use the discovery API methods to get an accurate list of available resources.
Fixes which technically should be considered backward-incompatible, when the affected part of the API was virtually unusable before the fix.
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.
Renaming or removing of an API method.
Removing mandatory request parameters of an API method.
Making previously optional request parameters mandatory.
Removing constant-named fields from API response structures.
Renaming, removing, or changing the meaning of a request parameter.
Renaming, removing, or changing the meaning of the possible value of enum-typed request parameters.
Changing the response structure of an API method.
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.