Versioning

As new capabilities are added over time, the API may change. This article describes the versioning strategy.

URL Versioning

The API version is built into the resource URLs. For example, /terminology/v1/standardize/condition.

Future significant or breaking changes may warrant a new version of the API. This would be hosted under a new version URL, such as /terminology/v2/standardize/condition.

Services may be versioned independently; e.g., the terminology collection may have both v1 and v2 while convert has only v1.

Backwards Compatibility

Care is taken to maintain backwards compatibility. Changes which are additive are considered backwards-compatible, and will generally not result in a new API version. These include (but are not limited to):

• Adding a new resource or collection.
• Adding a new request type (e.g., POST) to an existing resource.
• Adding a new response field to an existing request.
• Adding a new optional body/query parameter to an existing request.

Older version URLs will exist side-by-side with newer ones, allowing customers to upgrade at their own pace and discretion.