Semantic Versioning Api

title: "Semantic Versioning for APIs — Major, Minor, and Patch Versions" description: "Semantic versioning for APIs uses MAJOR.MINOR.PATCH format where major versions break backward compatibility and minor/patch versions add features or fix bugs." date: 2026-06-28 lastmod: 2026-06-28 weight: 18 tags: [apis, versioning] }

Semantic versioning (SemVer) for APIs uses MAJOR.MINOR.PATCH format: major versions contain breaking changes, minor add features backward-compatibly, patches fix bugs.

What You'll Learn

• SemVer specification
• What constitutes major, minor, patch
• SemVer for API vs software

Why It Matters

SemVer communicates change impact to clients. A major version bump warns of breaking changes; minor and patch indicate safe upgrades.

SemVer Rules

flowchart TD
    V[Version X.Y.Z] --> X{X = Major}
    X -->|Breaking changes| X2[Increment X]
    X -->|Backward compatible| Y{Y = Minor}
    Y -->|New features| Y2[Increment Y, reset Z]
    Y -->|Bug fixes| Z[Increment Z]

Code Examples

# SemVer in API response header
@app.route('/api/version')
def api_version():
    return jsonify({
        "version": "2.3.1",
        "major": 2,
        "minor": 3,
        "patch": 1,
        "status": "stable"
    })

# SemVer comparison for feature detection
def supports_feature(client_version, feature_since):
    client = tuple(int(x) for x in client_version.split('.'))
    since = tuple(int(x) for x in feature_since.split('.'))
    return client >= since

# Usage
client_ver = request.headers.get('X-Client-Version', '1.0.0')
if supports_feature(client_ver, '2.0.0'):
    return jsonify(new_feature_response())
else:
    return jsonify(legacy_response())

// SemVer in API
app.get('/api/info', (req, res) => {
  res.json({
    apiVersion: '3.0.0',
    deprecation: req.headers['x-api-version'] < '3'
      ? 'Please upgrade to v3'
      : undefined
  });
});

// Checking client semver
function checkVersion(clientVersion, minVersion) {
  const client = clientVersion.split('.').map(Number);
  const min = minVersion.split('.').map(Number);
  for (let i = 0; i < 3; i++) {
    if (client[i] > min[i]) return true;
    if (client[i] < min[i]) return false;
  }
  return true; // Equal
}

Common Mistakes

1. Breaking Changes in Minor Versions

Minor versions must be backward compatible. A breaking change requires a major bump.

2. No Version Manifest Endpoint

Clients need a way to discover the current API version.

3. Different Version for Different Endpoints

The API version should be consistent across all endpoints.

4. Pre-release Versions in Production

Avoid alpha/beta/rc versions in production API responses.

5. Not Communicating Version Changes

Publish changelogs and migration guides for every version.

Practice Questions

1. What does MAJOR.MINOR.PATCH mean?
2. What change requires a major version bump?
3. What change requires a minor version bump?
4. What change requires a patch version bump?
5. Why is SemVer important for API clients?

Answers:

1. MAJOR = breaking changes, MINOR = new features (backward-compatible), PATCH = bug fixes.
2. Breaking changes like removed fields or changed behavior.
3. New endpoints, fields, or optional parameters.
4. Bug fixes, performance improvements, security patches.
5. Clients know the risk level when upgrading between versions.

Challenge: Create a version manifest endpoint for your API that returns current version, changelog URL, deprecation dates, and migration guides.

FAQ