Wayfinder.Engine.Api 0.7.6

Wayfinder.Engine.Api

Exposes Wayfinder's service blueprint authoring — list, read, validate, save, simulate — as REST endpoints. This is a library, not a standalone service: a host calls MapServiceBlueprintAuthoringApi() from its own ASP.NET Core pipeline. See the AI-Ready Service Blueprint Authoring guide for the full integrator recipe, including the companion Wayfinder.Engine.Mcp package, which exposes the same operations as MCP tools.

Setup

builder.Services.AddSingleton<IServiceBlueprintSourceStore, YourServiceBlueprintSourceStore>();
builder.Services.AddServiceBlueprintAuthoring(); // Wayfinder.Engine.Extensions

var app = builder.Build();
app.MapServiceBlueprintAuthoringApi(); // defaults to prefix "/wayfinder/service-blueprint-authoring"

MapServiceBlueprintAuthoringApi() returns a RouteGroupBuilder — chain .RequireAuthorization() (or any other ASP.NET Core policy) the same way you would for any other endpoint group. This extension applies none itself.

Routes

All request/response bodies are ServiceBlueprint and friends from Wayfinder.Models.ServiceDesign — no bespoke DTOs except SimulateServiceBlueprintRequest, which bundles the simulate inputs.

validate/save/simulate never throw for an invalid blueprint — they report it in the response body.

Optimistic concurrency

PUT only saves if the body's version field still matches what's currently persisted — the same guarantee IProcessManager.Advance's expectedStateVersion already gives running instances, extended to definitions. There's no separate version parameter: a client that GETs a blueprint gets back its current version, and round-trips that same field in the body it later PUTs — that round-tripped value is the expected version. The store ignores whatever version the client sends as a value to persist; it only compares against it, then authoritatively sets the real new version itself, so a client can't fabricate an arbitrary version number.

A stale version returns 409 Conflict with a ServiceBlueprintSaveOutcome-shaped body ({ status: "Conflict", currentVersion, diagnostics }) — re-GET to see what's actually there now, reapply your change on top of it, and PUT again with the fresh version.

Every IServiceBlueprintSourceStore implementation must perform this compare-and-write atomically. The in-repo reference implementations (FilesystemServiceBlueprintSourceStore, FilesystemServiceBlueprintStore, Wayfinder.ReferenceApp's InMemoryRuntimeServiceBlueprintSourceStore) use an in-process lock — correct for a single-process app, but a real database-backed store should use an atomic UPDATE ... WHERE Version = @expectedVersion (the WHERE clause is the atomic compare) rather than a separate read-then-compare-then-write, which races under concurrent writers — see Wayfinder.Umbraco's UmbracoServiceBlueprintStore for a real example of that pattern against a database.

Reference implementation

Wayfinder.ReferenceApp (in this repo) wires this to InMemoryRuntimeServiceBlueprintSourceStore — see Program.cs. That store's SaveAsync calls engine.UpdateDefinition(...), so a save through this API is visible to the live running engine immediately — no restart. See the reference app guide for the full picture, including why nothing here touches disk.