Gera Tools

API Changelog Entry Builder

Document a breaking or non-breaking API change in a clear, standard format

Creates a structured API changelog entry with version, date, change type (breaking or non-breaking), affected endpoints, a migration guide, and a deprecation notice, then exports it as ready-to-paste Markdown. It runs free in your browser on Gera Tools, with nothing uploaded.

Last updated Source: Gera Tools

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.

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.

Example output

### v2.0.0 — 2026-06-15

**Type:** Breaking change

**Affected endpoints:**
- `GET /v1/users/{id}`
- `PATCH /v1/users/{id}`

**Summary:** The `name` field has been split into `first_name` and `last_name`.
Clients that write to or read from `name` must update to the new fields.

**Migration guide:**
1. Replace reads of `response.name` with `response.first_name + ' ' + response.last_name`.
2. Replace writes that set `name: "..."` with `first_name: "..."` and `last_name: "..."` separately.
3. Update any filtering or sorting that references `name` to reference `last_name`.

> ⚠️ **Deprecation notice:** The `name` field will be removed entirely on 2026-09-15.
> Clients still sending or requesting `name` after that date will receive a 400 error.

Breaking vs non-breaking: a practical checklist

Always breaking (requires MAJOR bump):

  • Removing a field from a response
  • Renaming a field or parameter
  • Changing a field’s type (e.g. string → object)
  • Adding a new required request field
  • Tightening validation on an existing field (e.g. max length reduced)
  • Removing an endpoint

Never breaking (MINOR or PATCH):

  • Adding a new optional response field
  • Adding a new endpoint
  • Adding a new optional request parameter with a sensible default
  • Loosening validation (e.g. max length increased)
  • Performance improvements with identical interface

Tips

  • For a breaking change, always pair the entry with a MAJOR version bump, e.g. v1.x → 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.
  • Send the changelog entry to API consumers via email or a developer newsletter, not just the docs — many integrators never check a changelog proactively.