UnifyUnitsDevelopers

Versioning

The API uses three independent version dimensions.

Dimensions

  • API version(/v1): encoded in the URL path. Breaking contract changes require a new major version.
  • Software version(0.1.0): internal implementation version. Not a compatibility boundary for API consumers.
  • Dataset version(X-UnifyUnits-Dataset-Version): tracks measurement factor updates.

Breaking vs non-breaking

Breaking (requires new version):

  • Removing or renaming a response field
  • Changing a field's type
  • Changing canonical unit identifiers
  • Changing error code semantics
  • Changing endpoint method or path

Non-breaking (stays in v1):

  • Adding optional response fields
  • Adding new endpoints, units, or categories
  • New optional request parameters with safe defaults
  • Dataset corrections for incorrect factors