Skip to main content

Version dialogs

Every change to a version goes through a dialog on Versions. This page covers each one, in the order you are likely to meet them.

New version​

Click “New version” in the page header.

  1. Copy source — Copy from version starts from an existing version's classes; leave it on Create blank version to start empty.
  2. Version — keep Auto-generate version and pick a Bump strategy (Minor by default, or Patch); the dialog shows the number it will create. Or choose Manual entry and type a Version ID such as 2.5.0.
  3. Describe the release — a Message is required (for example Add refund webhooks); External reference (a ticket id) and Changelog are optional.
  4. Click “Create version”.
The New version dialog: copy source, version strategy and bump, and the release message and changelogThe New version dialog: copy source, version strategy and bump, and the release message and changelog
Route/ade/dashboard/versions

Edit​

Click “Edit” on a row, or choose Edit from its Actions menu. The Version ID cannot change. You can set the Lifecycle (Stable, Beta, Deprecated, Archived), a Deprecation message, a Sunset date (entered in local time, stored as UTC), a Successor revision, and the Revision note and Changelog. Click “Save changes”.

On a published version the notes are frozen; only the deprecation and sunset metadata can change.

The Edit version dialog: lifecycle, deprecation message, sunset, successor, revision note and changelogThe Edit version dialog: lifecycle, deprecation message, sunset, successor, revision note and changelog
Route/ade/dashboard/versions

Publish​

Click “Publish” on a draft's row. Choose Private or Public, write a Revision note, check the Publish gates, and click “Publish”. The full walk-through, including Force publish (ignore validation errors), is in Version and publish.

The Publish dialog: visibility, revision note, changelog and the publish gates panelThe Publish dialog: visibility, revision note, changelog and the publish gates panel
Route/ade/dashboard/versions

Schedule sunset​

Choose “Schedule sunset (EOL)…” from a published version's Actions menu.

  1. Set Lifecycle to Deprecated — a sunset needs it.
  2. Write a Deprecation message telling consumers what to do.
  3. Pick the Sunset date and time (local time; stored in UTC).
  4. Pick the Successor revision consumers should move to, if there is one.
  5. Click “Save”.

The version then appears on the sunset timeline and in the deprecation banner on the timeline.

The Schedule sunset (EOL) dialog: revision, lifecycle, deprecation message, sunset date and successorThe Schedule sunset (EOL) dialog: revision, lifecycle, deprecation message, sunset date and successor
Route/ade/dashboard/versions

Compare​

Click “Compare” in the page header (it needs at least two versions). Pick Version 1 (base) and Version 2 (compare to), then click “Compare versions”. The result has five tabs:

  • Diff View — the two documents side by side;
  • Schema Changes — each version's revision note and changelog, with breaking hints;
  • Breaking doc — the compatibility report: whether the change is breaking, the rules that fired and where;
  • Migration guide — what consumers need to change;
  • Canvas — the two schema layouts, with added, removed and moved elements coloured.
Compare, Schema Changes: the base and compare versions' revision notes and changelogs side by side, with a breaking hintCompare, Schema Changes: the base and compare versions' revision notes and changelogs side by side, with a breaking hint
Route/ade/dashboard/versions
Compare, Breaking doc: the overall verdict, the rules that fired, and breaking and safe changes by pathCompare, Breaking doc: the overall verdict, the rules that fired, and breaking and safe changes by path
Route/ade/dashboard/versions
Compare, Canvas: the base and compare schema layouts with a legend for added, removed, moved and unchanged elementsCompare, Canvas: the base and compare schema layouts with a legend for added, removed, moved and unchanged elements
Route/ade/dashboard/versions

Export​

Choose “Export to another format…” from a row's Actions menu. Pick a target format, read its fidelity — what survives the conversion — and click “Export” (or “Export anyway” when the fidelity check warns). “Open in Export Studio” continues in the full Export studio.

The export panel: convert to any format, best-fidelity and lossy targets, and recent exportsThe export panel: convert to any format, best-fidelity and lossy targets, and recent exports
Route/ade/dashboard/versions

View spec from the same menu shows the generated OpenAPI document as JSON or YAML, with “Copy” and “Download”.

Git-like features​

Flag offFEATURE_GITLIKE

Apiome has branch, merge, fork and tag tooling for versions, but it is switched off: FEATURE_GITLIKE is a constant in apiome-ui/lib/feature-flags.ts, false in every shipped build. Production builds hide these controls; development builds draw them disabled with a gitlike marker. Turning them on takes a code change and a rebuild.

ControlWhat it would do
Merge branches (page header)Preview and apply a merge of two branches, resolving conflicts path by path
Branch from hereStart a named branch at a revision
Rollback branch to this revision…Revert a branch to an earlier revision
Fork to another project…Copy a revision into another project
Tag this revisionGive a revision a named tag
Compare with current, Relationship graphCompare against the head; show how revisions relate
Freeze schema, Lock revision (delete policy), DeleteProtect or remove a revision
Change report tabThe publication change report — see Versions
Merge conflicts, from a development build: two paths needing a resolution, with Mine, Theirs and Manual choicesMerge conflicts, from a development build: two paths needing a resolution, with Mine, Theirs and Manual choices
Route/ade/dashboard/versionsFrom a development build — this screen cannot be opened in a shipped build.

With the API​

POST /v1/versions/{tenant}/{project} (new), PUT /v1/versions/{tenant}/{project}/{version} (edit and sunset), POST …/publish, POST /v1/versions/{tenant}/{project}/compatibility and POST /v1/diff/{tenant}/classified (compare), POST /v1/export/{tenant}/document (export). See the API reference.

Where next​