Logic API

Publishing and versions

Publish an API draft as a major or minor version, start new drafts from published versions, and manage the version history.

An API’s versions are its release history. You design in the Draft; publishing turns the draft into a numbered, read-only version that the API host can serve. Use version numbers to tell callers what changed: a minor version adds things without breaking existing callers, a major version may break them.

Versions at a glance

	Draft	Published version
Version	`Draft`	`1.0`, `1.1`, `2.0` …
Editable in API Studio	Yes	No
Can be served to callers	For testing, if your host is set up for it	Yes
Can be the starting point of a new draft	No	Yes

Each API version also has Release Notes, where you describe what changed for the people who call the API.

Publish a draft

Before you publish, open the draft in API Studio, make sure the header shows no issues, and save.

In the app
From a pipeline

In the Logic Fabric API Builder app, open the API’s versions.
Select the draft.
Select Flowon APIPublish Major Version or Flowon APIPublish Minor Version.
Confirm “Are you sure you want to publish the selected draft?”.

Use the Logic Fabric CLI:

flowon-dynamics publish-api \
  --connectionstring "$DATAVERSE_CONNECTION" \
  --project "Contoso Service" \
  --api "Customer Portal API" \
  --version Minor

See publish-api.

Publish as	New version number	Use it when
Major	The next major number, for example `1.3` → `2.0`	You removed something callers use, changed a name they call, changed a field’s meaning, or tightened access.
Minor	The next minor number of the latest major, for example `2.0` → `2.1`	You only added endpoints, fields or optional inputs.

The draft itself becomes the new version. To keep working, start a new draft.

Start a new draft

Create a new API version and set its Baseline Version to the published version you want to build on. The new draft starts as a copy of that version. Without a baseline, the draft starts empty.

A draft cannot be the baseline of another version.

How it behaves

Publishing a draft with issues

Saving a draft records its issues. Publishing, from the app or from the CLI, refuses a draft that has issues, with a message such as:

This draft can’t be published because it has 2 issues. Open it in API Studio, fix them and save, then publish again:

…

Up to ten issues are listed. In the app the reason appears in an alert (“The draft was not published”); the CLI prints it and exits with code 1.

Deleting versions

You can’t delete a version that another version uses as its Baseline Version. Delete the versions built on it first, or keep it.

Changes that break callers

Some changes alter the addresses or shapes callers depend on. Publish them as a major version and tell the teams that call the API:

renaming a module or option set (see Modules and entities);
renaming or removing an action, query, input or returned field;
changing an input from optional to required;
adding or tightening an authorization policy.

OpenAPI schema

Each published version can be described as an OpenAPI (JSON) schema for developers and tools. Generate it with generate-openapi; see Introspection.

Example

The customer-portal API is at 1.2. The team adds a query for knowledge articles (a minor change) and, separately, renames the Portal module to SelfService (a change that breaks callers).

Create a draft with Baseline Version 1.2, add the query, save, and publish it as Minor → 1.3. Existing portal builds keep working.
Create a draft from 1.3, rename the module, save, and publish as Major → 2.0. The portal team switches to the /selfservice/... addresses when they move to 2.0.