Backward Compatibility Policy

This policy says what an integration built against the Coin Metrics API may rely on. It exists so that a client written today keeps working as the API changes, and so that the changes we consider routine are predictable rather than surprising.

The API is versioned with Semantic Versioning, as major.minor.patch. Backward incompatible changes raise the major number, backward compatible changes raise the minor number, and backward compatible fixes raise the patch number.

Versions

Major versions run in parallel, and choosing one is up to you. New major versions are published alongside existing ones, so clients of an existing version are unaffected by a release. Old major versions may be deprecated and eventually removed on a long-term schedule that gives clients time to migrate. Minor and patch releases replace the previous minor or patch within the same major version, and the version they replace stops being reachable.

Every major version carries a stability label, and the label determines how much of this policy applies.

Label	What it means
Stable	Covered by this policy in full. Backward incompatible changes are not made. Use a stable version in production.
Unstable	Fully tested, usable, and documented, but not covered by the compatibility rules below. It can change without warning. Intended for evaluating new features, not production.
Development	May change at any time and may be incomplete or broken. Avoid it.

A new major version is normally published as unstable, then becomes permanently stable after a period of stabilization. v4 is stable, and is the version this reference documents.

What may change in a minor or patch release

A change is backward compatible when a client built against an earlier version of the same major version still works. Each item below is something we may do at any time, paired with the assumption you therefore should not encode.

We may	So do not
Add an endpoint	Rely on a path or method being absent
Add a field to an existing response	Reject or fail on unrecognized fields
Add an optional request parameter, where omitting it preserves the previous behavior	Send parameters an endpoint does not document. They are ignored now, but may later be interpreted
Make a required parameter optional	Depend on a request being rejected for omitting it
Add a value to an enum-typed parameter	Assume the documented set of values is closed
Reword any human-facing string, including asset and metric names, descriptions, and error messages	Branch on message text. Branch on the stable fields instead, such as an error type
Add, remove, or change which assets, metrics, markets, and exchanges are available	Hard-code a resource list. Read it from reference data and catalog endpoints at run time
Fix behavior that was unusable enough that no working client could have depended on it	Rely on a defect

Which resources exist is not part of the API interface and is not covered by this policy. Assets, metrics, and markets are added and removed continuously, so a client that hard-codes them will break on a routine data change rather than on an API release.

What requires a new major version

These changes are made only in a new major version, or in one already labeled unstable or development. On a stable major version, you can assume they will not happen.

• Renaming or removing an endpoint.
• Removing a required request parameter.
• Making an optional request parameter required.
• Renaming a request parameter, or changing its meaning.
• Renaming or removing a value of an enum-typed parameter, or changing its meaning.
• Removing a fixed-name field from a response.
• Changing the structure of a response.

Emergency changes

Changes normally follow this policy. Breaking changes may still be made without a new major version where they are necessary to keep Coin Metrics services running, for security reasons, or where following the policy is not feasible. That includes introducing or changing rate limits, applying limits to a specific API key, and disabling a method or feature immediately. This policy itself may also change.

Such changes are rare, are made only after assessing the effect on clients, and come with as much advance notice as circumstances allow.

Related

• API Conventions: the cross-cutting behavior this policy governs, including the stable error type values.
• Rate limits: the current limits, which the emergency clause above allows us to change.