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.