API Design

Spec Versioning

Every API specification in Routebase is versioned. Versions let you evolve your API safely: drafts stay editable while released versions are frozen, consumers can be routed to the version they expect, and every release ships with a diff, a changelog, and a recorded change history. This guide covers the full version lifecycle — from creating a version to releasing, comparing, and resolving edit conflicts.

The version lifecycle

Each version moves through a fixed set of statuses:

Status Badge What it means
Draft Draft Work in progress. Changes can be made freely.
Review Review Under review. Awaiting approval before publishing.
Published Published Live and read-only. Changes require a new version.
Deprecated Deprecated Outdated. Consider upgrading to a newer version.

Published and deprecated versions are locked: the designer shows a banner — "Version 1.5.0 is published and cannot be edited." — with the hint to "Create a new version to make changes." A lock icon also appears next to locked versions in the version switcher.

Releasing a version freezes it, and freezing is permanent: a frozen version's contract can never change, and there is no "unpublish" that reopens it for edits. To move an environment off a version you rolled out, roll the environment's pin back instead — the pointer moves, but nothing is un-frozen. See Environments for promotion and rollback.

The version switcher in the header showing versions grouped by status with lock icons

Creating a version

  1. Open your spec in the API Designer and click the version indicator in the header (e.g. v1.5.0 with its status badge), then choose New Version.
  2. In the Create New Version dialog, pick a Quick Select bump — Major (Breaking changes), Minor (New features), or Patch (Bug fixes) — or type a Version Number yourself. Semantic versioning (Major.Minor.Patch) is required; the dialog shows your current latest version for reference.
  3. Choose the Content Source:
    • Copy from latest version — start from the most recent version's content.
    • Copy from specific version — pick any existing version from a dropdown.
    • Start with empty version — begin with a blank spec.
  4. Optionally add Release Notes describing what's new.
  5. Click create. The new version starts as a draft.

The version switcher

The header of the API Designer always shows the active version with its status badge. Click it to:

  • Switch between versions (grouped and badged by status, navigable with arrow keys).
  • New Version — open the create dialog.
  • Publish v{n} — open the release dialog for a draft or review version. Releasing requires the specs:publish permission; without it the entry is disabled with the tooltip "You need Admin or Owner role to publish". Members can edit drafts (specs:write) but cannot release.
  • Compare Versions — open the compare dialog (shown once you have two or more versions).
  • Compare with Previous — compare a draft or review version directly against the latest published version.

Versioning strategy

The Versioning Strategy card in the spec settings configures how API consumers specify which version to use. Five strategies are available:

Strategy Example
None Consumers always receive the latest version — no version-specific routing.
URL Path /v1/users
Header Api-Version: 1
Query Parameter ?version=1
Content Negotiation application/vnd.api.v1+json

Depending on the strategy, additional fields appear:

  • Parameter Name — the version carrier (defaults: v, Api-Version, version, or application/vnd.api).
  • URL Pattern (URL Path only) — e.g. /v{major}; supports the {major}, {minor}, and {patch} placeholders.
  • Default Version Behavior — what happens when a consumer sends no version: Latest version, Specific version, or Require explicit version.
  • Strict Mode — reject requests with invalid version identifiers.

A live Request Preview shows a curl example for the current configuration. Click Save Strategy to apply. Changing an existing strategy triggers a warning — "Change Versioning Strategy?" — because it may affect existing API consumers.

With no strategy configured, the panel notes: "No versioning strategy configured. Your API operates without version-specific routing. Consumers will always receive the latest version."

Version aliases and sunset dates

Below the strategy, a table lists your published and deprecated versions with columns for Version, Status, Alias, Sunset Date, and Actions. Aliases (e.g. v1 for 1.5.0) can be edited inline, and an Auto-suggest action proposes one from the version number. For deprecated versions you can set a sunset date to communicate when the version will be retired. Aliases and sunset dates become available after publishing.

Releasing a version

A release freezes a version into an immutable snapshot and, optionally, promotes it into one of your environments — a production release, a staging cut, or a plain frozen snapshot are all the same flow. Open the Release Version wizard via Publish v{n} in the version switcher (requires specs:publish). Its header reads "Freeze version {n} and promote it through your environments." The wizard has three steps.

Step 1 — Review changes

The first step compares the version against the last published one — a "Comparing with v{n} (last published)" banner with a View Full Diff button, or an Initial Release note for a first version — and shows a Changes Summary.

Below it, Pre-Publish Validation surfaces the version's style guide issues. Errors and warnings are listed with quick-fixes and Go to links that jump to the offending item. When your organization enforces the style guide on release, an error banner appears — "Style guide enforcement is active" / "Fix all style guide errors before releasing" — and those errors block the release. When nothing is wrong, a Ready to publish badge confirms "No validation issues found."

Step 2 — Version number and release notes

Pick the new Version Number with the Major (Breaking changes), Minor (New features), or Patch (Bug fixes) buttons — the analysis flags one as Suggested — or type a custom version. Then optionally build a Changelog: Auto-Generate produces structured entries from the diff, which you can preview, Copy, or apply with Use as Release Notes. Free-form Release Notes are "Optional notes visible to API consumers in the documentation."

Step 3 — Where to, and when

The final step chooses the target under Where to?:

  • Promote to {environment} — deploy the version into that environment. Each option shows what the environment runs today ("Currently runs {version}", "Nothing deployed yet", or "Freezes the version — immutable from here").
  • Freeze only — "Take an immutable snapshot without deploying anywhere."

If the chosen environment freezes versions, the trade-off is named before the click: "Promoting to {environment} freezes {version} — further changes need a new version. This cannot be undone." When the environment feeds the public docs, the alert adds that the documentation will be updated to match. If the version carries breaking changes against what the environment runs today, a second alert warns "N breaking changes since the version {environment} runs today ({version}). Consumers on that version may break."

For an environment target you also pick When? — Release now or Schedule release with a date and time (a scheduled release can be cancelled from the version's scheduled releases until it fires). Freeze only is always immediate.

A This will: panel spells out exactly what the button executes — for example Freeze {version} → Pin {environment} to {version} → Publish documentation v{n} → Build the public portal — so there are no surprises.

The action button reads Freeze (freeze only), Release to {environment}, or Schedule release. Blocking validation errors disable it and it reads Fix Errors to Release; if only non-blocking warnings remain, it asks for confirmation first — "Release with {summary}?" with Review Issues / Release Anyway.

The release receipt

After you release, the wizard replaces its steps with a live progress ladder that shows the real state of the chain instead of a to-do list. The freeze and the environment pin are done the instant the release returns; the documentation and portal build run in the background and the rows poll until they go live:

  • Snapshot frozen at {version} — the immutable snapshot.
  • {environment} pinned to {version} — for an environment promotion.
  • Documentation and portal updating — about a minute → Documentation v{n} is live once the background release finishes (only when the target environment feeds the public docs). A reassurance line confirms "Closing is safe — the documentation and portal finish publishing in the background."

If the target documentation requires approval, the row instead reads "Documentation v{n} synced — waiting for approval" with the note "A reviewer needs to approve the version before it goes live." A scheduled release shows when it will fire rather than a ladder.

Once the docs are embedded, View documentation, Copy link, and — for a public portal — Open public portal appear. A one-line summary flags any stale derived artifacts (mocks, tests, monitors) that no longer match the frozen contract, opening a review sheet.

Exports

Every frozen snapshot can be downloaded directly from the receipt, in YAML, JSON, Postman or Insomnia form. The buttons appear only once the version is actually frozen — a non-freezing promotion leaves it a draft, and a draft has no snapshot to export. Formats and what travels with them: Import & Export.

Comparing versions

Open Compare Versions from the version switcher. In the dialog, select a Source (older) and Target (newer) version.

  • A classified summary banner counts Breaking Changes, Improvements, and Deprecations. If breaking changes are detected, an alert recommends reviewing the migration guides below before upgrading.
  • The summary panel lists endpoints and schemas that were added, removed, or modified; if the versions are identical it reports that no differences were found.
  • Tabs let you drill down: Overview, Endpoints, Schemas, and Classifications (with All / Breaking / Deprecated filters). Endpoint entries expand to show field-, parameter-, and response-level changes, with migration hints on breaking changes.
  • Generate Changelog turns the comparison into changelog entries you can review, select, and copy as Markdown.

What counts as breaking

The classification is not a judgement call — 21 rules decide it, the same ones every time, so two people comparing the same pair of versions get the same answer.

Breaking — an existing consumer can stop working:

Change Why it breaks
An endpoint is removed Calls to it start failing.
An endpoint's path changes Same thing, from the caller's side.
An endpoint's method changes The old method no longer answers.
A parameter is removed Callers still sending it may be rejected.
A parameter's type changes Existing values may no longer be valid.
An optional parameter becomes required Callers that omit it start failing.
A new required parameter is added Every existing call is missing it.
A new required request-body field is added Same, in the body.
A new required field is added to a request schema Same, one level down.
A schema field becomes required Existing payloads may not carry it.
A response field is removed Consumers reading it get nothing.
A response field's type changes Consumers parsing it may fail.
An enum value is removed Callers sending it are rejected.

Non-breaking — additive or cosmetic:

Change Why it's safe
An optional parameter is added Existing calls stay valid.
A response field is added Consumers ignore what they don't read.
An enum value is added Only new values appear; old ones still work.
A schema field becomes optional Anything that was valid before still is.
A description, summary, or example changes No effect on the wire.

Deprecation is its own class: marking an endpoint deprecated changes nothing technically but signals intent, so it is counted separately rather than hidden among the safe changes. See deprecating an endpoint.

One asymmetry is worth internalizing: adding a required field is breaking, removing one is not, and it is the other way round for response fields. The rule behind both is the same — whatever the other side has to provide may only get easier, whatever it receives may only get richer.

History

  • The History tab of a spec shows the Change History: a timeline of every change with timestamp, user, affected entity, and change type — including when a version was published (frozen) — with its version number. Click an entry to see its diff. The tab header shows the change count and when the spec was last modified.

Concurrent editing and conflicts

Routebase supports real-time collaboration, and it protects you when two people edit the same thing:

  • Editing lock banner — while someone else is editing an item, a banner shows "{user} is currently editing this {type}".
  • Remote change banner — if another user saved changes to an item where you have unsaved edits, a banner appears: "{user} updated {entity}. You have unsaved changes." Choose Keep My Changes or Reload.
  • Conflict Detected dialog — when your save collides with a newer server state, a resolution dialog opens. Fields that don't actually conflict are merged automatically and summarized ("N field(s) auto-merged (no conflict)"). For each real conflict you see Your Version next to the Server Version — with a side-by-side diff for long fields — and choose mine, theirs, or a custom value. Bulk actions Keep All Mine and Use All Server apply one side everywhere; Apply Merge saves the result. If everything merges cleanly, the dialog says so and Apply Merge is all you need.

Branches and merge requests

For larger changes you can branch a spec instead of editing it directly, review the result, and merge it back into the main draft. Branching is available on the Pro plan and above and requires specs:branch.

A branch is taken from a draft version and merges back into that same draft version — it is not a way to change a published version, and a merge is not a release.

Branching covers the whole workflow: the branch switcher, creating and working on a branch, rebasing (including how conflicts are resolved), merge requests with their review and comment tabs, and the conditions a merge has to satisfy.