API Design

Spec Versioning

Every API specification in Routebase is versioned, which lets 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 reading "Version 1.5.0 is published and cannot be edited." with the hint to "Create a new version to make changes." Locked versions also carry a lock icon 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, because the pointer moves without un-freezing anything. See Environments for promotion and rollback.

The version switcher in the header with a draft, a published and a deprecated version, lock icons on the frozen ones

Creating a version

  1. Open your spec in the API Designer and click the version indicator in the header, which reads something like v1.5.0 with its status badge. Choose New Version.
  2. In the Create New Version dialog, pick a Quick Select bump or type a Version Number yourself. The bumps are Major for breaking changes, Minor for new features and Patch for bug fixes. Semantic versioning in the form Major.Minor.Patch is required, and the dialog shows your current latest version for reference.
  3. Choose the Content Source:
    • Copy from latest version starts from the most recent version's content.
    • Copy from specific version lets you pick any existing version from a dropdown.
    • Start with empty version begins with a blank spec.
  4. Optionally add Release Notes describing what is 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, which are grouped and badged by status and navigable with the arrow keys.
  • New Version opens the create dialog.
  • Publish v{n} opens the release dialog for a draft or review version. Releasing requires the specs:publish permission, and without it the entry is disabled with the tooltip "You need Admin or Owner role to publish". Members can edit drafts with specs:write but cannot release.
  • Compare Versions opens the compare dialog, which appears once you have two or more versions.
  • Compare with Previous compares 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 is the version carrier, and it defaults to v, Api-Version, version or application/vnd.api depending on the strategy.
  • URL Pattern appears for URL Path only, takes a value such as /v{major}, and supports the {major}, {minor} and {patch} placeholders.
  • Default Version Behavior decides what happens when a consumer sends no version, offering Latest version, Specific version and Require explicit version.
  • Strict Mode rejects 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 reading "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. Every published and deprecated version has a row, whether or not it carries an alias yet, so you set the first one here. Aliases such as 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. While a specification has no published version, the table is replaced by the note "No published or deprecated versions yet. Aliases and sunset dates become available after publishing."

Releasing a version

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

The Release Version wizard on the Where to? step with Freeze only and environment targets

Step 1 — Review changes

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

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 reading "Style guide enforcement is active" and "Fix all style guide errors before releasing" appears, 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, Minor or Patch buttons, which stand for breaking changes, new features and bug fixes. The analysis flags one of them as Suggested, and you can also type a custom version. Then optionally build a Changelog, where Auto-Generate produces structured entries from the diff that 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} deploys the version into that environment. Each option shows what the environment runs today, reading "Currently runs {version}", "Nothing deployed yet" or "Freezes the version — immutable from here".
  • Freeze only does what its description says, which is "Take an immutable snapshot without deploying anywhere."

If the chosen environment freezes versions, the trade-off is named before the click, reading "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?, which is either 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, while Freeze only is always immediate.

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

The action button reads Freeze for a freeze only, Release to {environment} for a promotion, 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 with "Release with {summary}?" and the choices Review Issues and 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, while the documentation and portal build run in the background and the rows poll until they go live:

  • Snapshot frozen at {version} names the immutable snapshot.
  • {environment} pinned to {version} appears for an environment promotion.
  • Documentation and portal updating — about a minute turns into Documentation v{n} is live once the background release finishes. This row appears 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". The note below it says "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 and Copy link appear, and a public portal adds Open public portal. A one-line summary flags any stale derived artifacts such as mocks, tests and monitors that no longer match the frozen contract, and it opens 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, because a non-freezing promotion leaves it a draft and a draft has no snapshot to export. Import & Export covers the formats and what travels with them.

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 into Overview, Endpoints, Schemas and Classifications, the last of which carries All, Breaking and Deprecated filters. Endpoint entries expand to show changes at field, parameter and response level, 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, because 22 rules decide it. They are the same rules every time, so two people comparing the same pair of versions get the same answer.

Breaking, meaning 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, meaning additive or cosmetic:

Change Why it's safe
An optional parameter is added Existing calls stay valid.
A path parameter is renamed The placeholder name lives in the template, not in the URL a client calls.
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 while removing one is not, and it is the other way round for response fields. The rule behind both is the same, because whatever the other side has to provide may only get easier, and whatever it receives may only get richer.

History

The History tab of a spec shows the Change History, which is a timeline of every change with its timestamp, user, affected entity and change type. Publishing a version is recorded there too, with its version number, under the label frozen. 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:

  • The editing lock banner shows "{user} is currently editing this {type}" while someone else is editing an item.
  • The remote change banner appears if another user saved changes to an item where you have unsaved edits, and it reads "{user} updated {entity}. You have unsaved changes." Choose Keep My Changes or Reload.
  • The Conflict Detected dialog opens when your save collides with a newer server state. Fields that do not actually conflict are merged automatically and summarized as "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 you choose mine, theirs or a custom value. The bulk actions Keep All Mine and Use All Server apply one side everywhere, and 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. That includes the branch switcher, creating and working on a branch, and rebasing with how conflicts are resolved there. It also covers merge requests with their review and comment tabs, and the conditions a merge has to satisfy.