Skip to content
FlowonFlowonLogic Fabric DocsLogic Fabric Docs
flowon.com

Logic API

Versions and updates

Choose which version of an API a host serves, and how the host picks up a changed draft or a newly published version.

A Logic API has a draft and published versions such as 1.0, 1.1 and 2.0 (see Publishing and versions). Each host serves exactly one of them. The versioning strategy decides which one; the metadata watcher decides how the host notices that the draft changed or a newer version was published.

Versioning strategies

Section titled “Versioning strategies”

Set the strategy in AddRestServer:

.AddRestServer(options =>
{
    options.VersioningStrategy = new LatestVersionApiVersioningStrategy();
})
Strategy Serves Picks up changes with the metadata watcher Use it for
DraftVersionApiVersioningStrategy The API’s current draft, including unpublished changes. Yes: whenever the draft is saved. Development, so designers see their changes without publishing.
LatestVersionApiVersioningStrategy (default) The highest published version, for example 2.1 when 1.0, 2.0 and 2.1 exist. Yes: when a newer version is published. Test environments, and production when you want every new version to go live as soon as it’s published.
ExactVersionApiVersioningStrategy One specific published version, set with ApiVersion = new ApiVersion(2, 1). No: it serves that version until you change the setting. Production when releases must go live at a time you choose, and hosts that keep an older version available.

The example host reads the strategy from the LogicApi:Version setting (draft, latest or 2.1), so each environment chooses its own without a code change:

Environment LogicApi:Version Why
Development draft Designers test changes before publishing.
Test latest Every published version is tested as soon as it exists.
Production 2.1 (or latest) You decide when callers move to a new version by changing the setting.

Serving several versions

Section titled “Serving several versions”

A host serves one version. To keep an older version available while callers move to a newer one, run two hosts, for example https://partner-v1.api.contoso.com with LogicApi:Version = 1.4 and https://partner-v2.api.contoso.com with 2.1. Callers choose the version by address. Retire the old host when its callers have moved.

A version that can’t be served

Section titled “A version that can’t be served”

When the host starts, it loads and checks the version the strategy selects. If it can’t (for example latest before any version is published, a version number that doesn’t exist, or a version that contains errors), the host can’t serve that version and its log says why. Publish a fixed version, or point the setting at another version.

The metadata watcher

Section titled “The metadata watcher”

The host loads the API definition once, when it starts. To pick up a changed draft or a newly published version without a manual restart, add the metadata watcher:

.AddMetadataWatcher(options => options.TimeIntervalInMinutes = 5)

What it does:

  1. Every TimeIntervalInMinutes minutes (default 5), it asks Dataverse whether the version the strategy selects has changed: a later save of the draft, or a newer published version for latest.
  2. If it has, the watcher stops the host.
  3. Your hosting platform starts the host again, and the new instance loads the new version at startup.

It works with the draft and latest strategies. With an exact version there’s nothing to watch, and the watcher does nothing.

Plan for the restart

Section titled “Plan for the restart”
  • The platform must restart the host. Azure App Service, container platforms with a restart policy (Azure Container Apps, Kubernetes), and IIS start the application again after it stops. A process you run by hand, or a Windows service without recovery actions, stays stopped.
  • Expect a short gap. Calls that arrive while the host restarts fail or wait. With several instances behind a load balancer, they all restart within the watch interval; schedule publishing to production outside busy hours, or use an exact version and change it in a planned release.
  • Changes take up to one interval. A published version goes live within TimeIntervalInMinutes minutes plus the restart time. Shorter intervals mean more frequent checks against Dataverse; one to five minutes is usual.

Without the watcher

Section titled “Without the watcher”

Leave out AddMetadataWatcher and the host keeps serving what it loaded at startup. Restart it yourself to pick up a new draft or version, for example as the last step of your release pipeline.

Section titled “Recommended setup”
Environment Strategy Watcher
Development Draft On, with a short interval (1–2 minutes)
Test Latest On
Production Exact version, changed by your release process Not needed
Production, continuous delivery Latest On, and publish outside busy hours
Section titled “Related”