The list of currently available versions is available at API documentation home page.
If you just started working with Coin Metrics API, use the latest stable version.
If you are already using some stable version, you are encouraged to switch to the latest stable version eventually. Later stable version usually provides more features and other improvements. You can also use multiple versions simultaneously.
In any case no development version should be ever used in production.
Major versions of API are run in parallel. The choice of what major API version to use is up to a client.
Major versions can be marked as stable or unstable. As backward incompatible changes can be introduced only in unstable or development major version, no breakage is expected when using fixed stable major API version (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 (generally long-term) deprecation schedule, giving clients time to adapt their implementations to new major version.
Minor and patch releases replace old minor/patch API version, under the same major version. Old minor/patch API version becomes inaccessible.
Recently introduced version of API may be explicitly labeled "unstable". Unstable API version is meant to be fully tested, usable by clients, and have complete documentation. However unstable API is not covered by the backward compatibility rules below, and can receive arbitrary changes at any time without any warning. It is advised to not use it in production. Use it only for evaluation of new features.
New major versions of API are expected to be marked unstable, and after period of stabilization and testing become permanently stable.
The newest version of API may be explicitly labeled "development". Development API version is not only may receive arbitrary changes at any time, but it also can have wrong/incomplete implementation, documentation, or other critical issues. Generally development API version should be completely avoided, as there's no guarantees at all about how well it works, or whether it works at all.
Change is backward compatible when an API client built for old version of API still works with new version. Hence it is important that API clients use correct assumptions about what details of API they can rely on.
These changes can be introduced in minor or patch API version. Please follow the recommendations below to not get your integration broken.
Addition of 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 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 parameter optional.
Addition of new possible values for enum-typed request parameters of 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 asset/metric/etc is not part of API interface and not covered by this policy: you should use discovery API methods to get actual list of available resources.
Fixes which are technically should be considered backward-incompatible, when affected part of the API was virtually unusable before the fix.
These changes can only be introduced in new major API version, or unstable major API version. It is safe to assume it will not happen while you use fixed stable major API version.
Renaming or removing of an API method.
Removing mandatory request parameter of an API method.
Making previously optional request parameter mandatory.
Removing constant-named fields from API response structures.
Renaming, removing, or changing meaning of request parameter.
Renaming, removing, or changing meaning of possible value of enum-typed request parameter.
Changing response structure of an API method.
Generally changes to API interface and functionality will follow this policy as outlined above. However breaking changes may still be made without introducing new major version, if it is needed for continuous operation of our services, for security reasons, or for other reasons, if following this policy is not deemed possible. That may include, but not limited to, the following: introducing or changing request rate limits, applying specific limits per specific API key, immediate disabling of specific method or feature, and so on. Changes also can be made to this policy.
Such emergency changes are expected to be an exception, not a rule, and should be conducted only after assessment of impact for clients, and with as much advance notice as possible.