dkduckkit.dev

API Versioning Decision Helper

Interactive SemVer: decide major, minor, or patch bumps with clear rationale for API changes.

Last updated: March 2026

TL;DR

Walk additive, deprecating, and breaking API edits to pick the correct SemVer bump with rationale your team can paste into changelogs.

Formula: Breaking change → major; backward-compatible feature → minor; fixes without API contract change → patch.

When to use this

  • Before publishing SDKs or public OpenAPI after a release train.
  • Aligning platform and product teams on consumer impact.

Related glossary

How the math works

How the math worksLaTeX model and TypeScript reference — same logic as the calculator on this page.

This describes the implementation behind the numbers as of 2026-03-26. It is engineering documentation, not legal or compliance advice.

Specification citation

Logic reflects our proprietary implementation of the following public specifications: Semantic Versioning 2.0.0.

This snippet represents the core logic of our proprietary calculation engine, verified against Semantic Versioning 2.0.0.

Model (LaTeX source)
SemVer bump selection (duckkit.dev rules)

Each selected change c has type t(c) ∈ { breaking, feature, fix }.

bump =
  major  if ∃c : t(c) = breaking
  minor  else if ∃c : t(c) = feature
  patch  otherwise

Matches SemVer precedence: incompatible API → MAJOR; backward-compatible additions → MINOR;
fixes without contract change → PATCH.
Reference implementation (TypeScript, excerpt from shipped modules)
// lib/api-versioning/decision-logic.ts
export function calculateBump(selectedIds: string[]): DecisionResult {
  if (selectedIds.length === 0) return { bump: 'none', ...RESULTS.none }

  const selected = CHANGES.filter((c) => selectedIds.includes(c.id))
  const hasBreaking = selected.some((c) => c.type === 'breaking')
  const hasFeature = selected.some((c) => c.type === 'feature')

  const bump = hasBreaking ? 'major' : hasFeature ? 'minor' : 'patch'
  return { bump, ...RESULTS[bump] }
}

No SemVer bump. Select one or more API changes below.

At a glance

Recommended bump
—

Breaking Changes

New Features

Bug Fixes & Maintenance

Recommendation

Select one or more changes above to get a versioning recommendation.

Methodology

Each checkbox maps to a change type (breaking, feature, or fix). With at least one selected, the bump is major if any breaking change is selected; otherwise minor if any feature is selected; otherwise patch (fixes only). With nothing selected, the result is none. This is an opinionated helper aligned with common SemVer practice — it does not parse your repository or diff OpenAPI specs.

Understanding Semantic Versioning (SemVer)Semantic Versioning (SemVer)MAJOR.MINOR.PATCH scheme communicating compatibility changes.Read more →

Semantic versioning (SemVer) is a versioning scheme that helps API developers communicate the impact of changes to their consumers. When you bump your API version, you signal whether existing clients need to update their code or can safely upgrade.

When to bump majorMajor, minor, and patch bumps (API)Patch fixes bugs, Minor adds features, Major breaks compatibility.Read more → version

A major version bumpMajor, minor, and patch bumps (API)Patch fixes bugs, Minor adds features, Major breaks compatibility.Read more → indicates breaking changesBreaking change (API)Modification causing existing clients to fail or require updates.Read more → that make your API incompatible with previous versions. If you remove endpoints, rename fields, change response shapes, or modify authentication — existing consumers will need to update their integration. This is when you bump the major number (e.g., v1.0.0 → v2.0.0).

When to bump minor version

A minor version bump signals backward-compatible new functionality. Adding optional parameters, new endpoints, or optional response fields does not break existing clients. They can upgrade without code changes. Bump the minor number (e.g., v1.4.2 → v1.5.0).

When to bump patch version

A patch version bumpMajor, minor, and patch bumps (API)Patch fixes bugs, Minor adds features, Major breaks compatibility.Read more → is for backward-compatible bug fixes. Fixing incorrect behavior, improving performance, or updating documentation without changing the API contract qualifies as a patch. Bump the patch number (e.g., v1.4.2 → v1.4.3).

For the full specification, see semver.org.

Teams often pair SemVer with consumer-driven contractsConsumer-driven contractsConsumers define expectations; provider runs contracts as tests.Read more → to catch incompatible changes before release, and use a Sunset headerSunset header (API)Communicates when resource or version will be decommissioned.Read more → (or equivalent) so clients know when a version will be retired.

SemVerSemantic Versioning (SemVer)MAJOR.MINOR.PATCH scheme communicating compatibility changes.Read more → vs calendar versioningCalendar Versioning (CalVer)Version tied to release dates rather than compatibility signals.Read more →

SemVerSemantic Versioning (SemVer)MAJOR.MINOR.PATCH scheme communicating compatibility changes.Read more → signals compatibility from version numbers; CalVerCalendar Versioning (CalVer)Version tied to release dates rather than compatibility signals.Read more → encodes release time. Public APIs usually pick SemVer so clients can reason about breaking changesBreaking change (API)Modification causing existing clients to fail or require updates.Read more →—use this tool for SemVer decisions.

Not sure which fields changed? Use our API Breaking Change Checker to diff two JSON Schemas automatically before you pick a bump here.

Copy-paste solution

## API change checklist (paste into PR)
- [ ] Breaking: removed/renamed fields or stricter validation → MAJOR
- [ ] Non-breaking new optional fields → MINOR
- [ ] Bugfix, same contract → PATCH
- [ ] Linked OpenAPI / JSON Schema diff attached

Frequently asked questions

When should I bump the major version of my API?▾
Bump major (v1 → v2) when existing clients would break without code changes: removing a field, changing a field's type, renaming an endpoint, changing authentication requirements, or making a previously optional field required. The test: if a client written against v1 would fail or behave incorrectly against the new version, it's a major bump.
What is the difference between URL versioning and header versioning?▾
URL versioning (/v1/users vs /v2/users) is explicit and easy to test in a browser, but pollutes routes. Header versioning (Accept: application/vnd.api+json;version=2) is cleaner but harder to debug and cache. For public APIs, URL versioning is the safer default because it's visible, cacheable by CDNs, and requires no client configuration.
Is adding a new optional field a breaking change?▾
Usually not, but it depends on the consumer. Strictly typed consumers (e.g., generated from a schema) may fail on unknown fields if they use strict deserialization. Consumers using lenient JSON parsers will ignore it. Best practice: treat adding optional fields as non-breaking, but document it as a minor version bump and test that your known consumers handle unknown fields gracefully.
What is the Sunset header and when should I use it?▾
The Sunset header (RFC 8594) tells clients when an API endpoint will be decommissioned: Sunset: Sat, 31 Dec 2026 23:59:59 GMT. Use it during deprecation periods so clients can see the deadline in HTTP responses rather than only in documentation. Combine it with a Link header pointing to a migration guide.
How long should an API deprecation period last?▾
Minimum 6 months for external/public APIs, 3 months for internal APIs with known consumers. The deprecation period starts when you announce it (not when the new version ships) and ends when you stop serving the old version. Monitor actual usage of deprecated endpoints — if traffic is still high at the end of the period, extend it rather than breaking active clients.

Related glossary

Semantic Versioning (SemVer)Major, minor, and patch bumps (API)Breaking change (API)Calendar Versioning (CalVer)

Related tools