Skip to main content

API versioning & lifecycle

This page describes how the MyTrafficData external API is versioned.

URL-based major versioning​

The API major version appears in the URL path:

https://mytrafficdata.com/api/v1/traffic/sites
                              ^^^^
                              major version

The current major version is v1. All endpoints documented on this site live under /api/v1/.

When a new major version is released, it lives under a new path prefix (/api/v2/, /api/v3/, …) and runs in parallel with the previous one. You upgrade by changing the URL prefix in your client.

How versions get bumped​

Internally we follow Semantic Versioning and Conventional Commits. The platform release version is calculated automatically from commit history:

Commit prefixBumps
feat:Minor version
fix: / perf: / refactor:Patch version
Commit with BREAKING CHANGE: footerMajor version

A BREAKING CHANGE: is what causes a new API major (e.g. /api/v2/) to ship.

The platform release version (v10.x.y) is not the API major version (v1, v2). The API major lives in the URL prefix and bumps only when we actually break the wire contract.

What's in a major​

A major version is a snapshot of the API contract: every endpoint, request shape, response shape, error code, and field name available at that prefix.

Inside a major, we ship non-breaking changes continuously without bumping the version:

Roughly: additive changes are non-breaking (new endpoints, new optional request parameters, new response fields, looser validation), while anything that removes, renames, retypes or tightens what already exists is breaking.

The exact classification is maintained in one place — this page deliberately does not restate it, because a partial copy that looks authoritative is worse than a pointer. See Breaking-change policy for the full list.

Discovering the current version​

There is no GET /api/versions discovery endpoint. The canonical list of supported majors is this documentation site — specifically the sidebar's API reference section.

Minor and patch changes​

We don't expose minor or patch versions in the URL — they're implementation details. The major version covers the public contract, which is the only thing that affects integrators.

Summary checklist​

  • ✅ Current major: v1. Path prefix: /api/v1/.
  • ✅ Non-breaking changes ship continuously inside a major.
  • ✅ Breaking changes require a new major (/api/v2/, etc.). Internally tracked via Conventional Commits + BREAKING CHANGE: footers.
  • ✅ No version-discovery endpoint — this docs site is canonical.