Metric Versioning

Metric Versioning tracks changes to metric definitions over time, providing a complete history of modifications with the ability to compare versions and rollback to previous definitions. This ensures that changes to business metrics are auditable and reversible. All versioning endpoints are served at the base path /api/v1/metrics/versions.

How Versioning Works

Every time a metric definition is modified (expression, type, filters, or configuration), a new version is created. The system maintains the full history of versions, allowing users to review changes, compare definitions, and restore previous versions.

Version 1: SUM(order_total)
    |
    v (updated expression)
Version 2: SUM(order_total) WHERE status = 'completed'
    |
    v (added filter)
Version 3: SUM(order_total) WHERE status = 'completed' AND region IS NOT NULL
    |
    v (rollback to version 1)
Version 4: SUM(order_total) [restored from v1]

Endpoints

Method	Path	Description
`GET`	`/api/v1/metrics/versions/:metricId/history`	Get full version history
`GET`	`/api/v1/metrics/versions/:metricId/versions/:version`	Get a specific version
`GET`	`/api/v1/metrics/versions/:metricId/current`	Get current version number
`GET`	`/api/v1/metrics/versions/:metricId/compare`	Compare two versions
`POST`	`/api/v1/metrics/versions/:metricId/rollback`	Rollback to a previous version

Version History

Retrieves the complete list of versions for a metric, ordered from most recent to oldest.

Request:

GET /api/v1/metrics/versions/550e8400-.../history
X-Tenant-ID: tenant-uuid

Response: A list of MetricVersion objects, each containing the version number, metric definition snapshot, change description, author, and timestamp.

Get Specific Version

Retrieves a specific version by number.

Request:

GET /api/v1/metrics/versions/550e8400-.../versions/2
X-Tenant-ID: tenant-uuid

Returns a 404 Not Found if the version number does not exist.

Current Version

Returns the current (latest) version number for a metric.

Request:

GET /api/v1/metrics/versions/550e8400-.../current
X-Tenant-ID: tenant-uuid

Response:

Version Comparison

Compares two versions of a metric to identify what changed between them.

Parameter	Type	Required	Description
`fromVersion`	Integer	Yes	Earlier version number
`toVersion`	Integer	Yes	Later version number

Request:

GET /api/v1/metrics/versions/550e8400-.../compare?fromVersion=1&toVersion=3
X-Tenant-ID: tenant-uuid

Response: A MetricVersionDiff object containing the differences between the two versions, including changed fields, added filters, modified expressions, and metadata changes.

Rollback

Restores a metric to a previous version by creating a new version with the old definition. This does not delete intermediate versions; it creates a new version entry that references the target version.

Parameter	Type	Required	Description
`targetVersion`	Integer	Yes	Version number to restore

Headers:

Header	Required	Description
`X-Tenant-ID`	Yes	Tenant identifier
`X-User-ID`	Yes	User performing the rollback

Request:

POST /api/v1/metrics/versions/550e8400-.../rollback?targetVersion=1
X-Tenant-ID: tenant-uuid
X-User-ID: user-uuid

Response: The newly created MetricVersion with the restored definition and an incremented version number.

Version Record Fields

Each version record stores the following information.

Field	Description
`versionNumber`	Sequential version identifier
`metricDefinition`	Complete snapshot of the metric at this version
`changeDescription`	Human-readable description of what changed
`changedBy`	User who made the change
`createdAt`	Timestamp when the version was created
`isRollback`	Whether this version was created by a rollback operation
`rollbackSource`	If a rollback, the version number that was restored

Best Practices

Review the version diff before rolling back to understand what will change
Use meaningful change descriptions when updating metrics
Monitor the current version number to detect unexpected changes
Combine versioning with governance audit policies for complete metric change tracking
Coordinate metric changes with downstream dashboard and report consumers

Advanced Metrics Model Relationships