What makes an API change breaking versus non-breaking?

A breaking change forces existing clients to update code — removing a field, renaming a parameter, changing a response shape, or tightening validation. Non-breaking changes are additive, like a new optional field or endpoint, and old clients keep working untouched.

How does this relate to semantic versioning?

Under SemVer, breaking changes bump the MAJOR version, backward-compatible features bump MINOR, and fixes bump PATCH. The builder flags breaking changes so you can pick the correct version number before publishing.

Why include a deprecation notice?

A deprecation notice warns consumers that a field or endpoint will be removed on a future date, giving them a window to migrate. Announcing removals ahead of time, rather than deleting silently, prevents broken integrations.

What should a migration guide contain?

It should show the old call and the new call side by side, name every changed field, and give the minimum steps to upgrade. Concrete before-and-after examples cut support load dramatically.

Is the output ready to paste into a changelog file?

Yes. The tool emits standard Markdown with a heading, metadata, an affected-endpoints list, and migration steps, so you can drop it straight into CHANGELOG.md or a release note with no reformatting.

API Changelog Entry Builder

Email me this result

Get this tool's output sent to your inbox, plus one useful tool a week. No spam, unsubscribe any time.

Document API changes so consumers never get surprised

Every change to a public API ripples out to everyone who built against it. A clear changelog entry — version, date, what changed, which endpoints are affected, and how to migrate — is the difference between a smooth upgrade and a flood of broken-integration tickets. This builder turns a few inputs into a consistent, paste-ready Markdown entry.

How it works

You supply the version, ship date, change type, a list of affected endpoints, a summary, and migration steps. The tool assembles a Markdown block using a conventional changelog shape: an H3 heading with the version and date, a bold Type line, a bulleted list of affected endpoints, the summary, a numbered migration guide, and — when you set a removal date — a clearly marked deprecation notice. Breaking changes are highlighted so you remember to bump the MAJOR version under semantic versioning before you publish.

Tips and example

For a breaking change, always pair the entry with a MAJOR version bump, e.g. v1.x to v2.0.0.
List endpoints in METHOD /path form, such as GET /v1/users/{id}, so readers can scan them fast.
In the migration guide, show the old request and the new request as fenced code blocks — concrete before-and-after beats prose.
Set a deprecation date at least one MINOR cycle ahead of removal so consumers have a real migration window.