Documentation for v2.8.0. Read the latest, v2.12.0.

Developer

The web UI

Everything a build records is browsable. This chapter walks the pages a developer opens: Producers and their version lines, the spec viewer, Consumers and their pins, the dependency graph and the reports. The admin page is Administration in the Operator track.

The landing page and the validator#

/ needs no login. Its Try it form is the validator: paste an OpenAPI, AsyncAPI or Protobuf document and Sanshain runs exactly the provide-side checks, version extraction and endpoint splitting, and shows the version it read and a preview of the endpoints it would store. Nothing is saved. The same check is POST /validate, unauthenticated.

The account page#

/account.html is where you change your password and mint API tokens: a name, an expiry in days, and the Read-only (for AI / MCP clients) box that sets the scope to read_only. The raw token is shown once. The list below shows every token you own with its scope, its expiry and when it last authenticated a request, to the minute, and lets you revoke it. The star next to a Producer on the Producers page marks it as one of your favourites.

Producers#

/producers.html lists every Producer with a search box. A Producer opens to its version lines, one card per API type, each version a row with its stability, endpoint count, who provided it and when. Badges on a row:

• GA or snapshot.
• Expires in N d on a snapshot when cleanup is on: the use-based expiry.
• superseded by X ga on a snapshot below the latest GA of its line: Consumers pinning it should move.
• trunk when trunk CI last provided this version, and a chip per sanshain-branch that references it.

Expanding a row lists the endpoints of that version, each with a deprecated badge where the spec marks it and a count of the Consumers that pin it; clicking one opens its snippet in the spec viewer, where it can be copied or downloaded. View spec opens the whole document in the viewer; Download saves it; Delete is the audited escape hatch for admins and the Producer's maintainers, and it lists the pinned Consumers and referencing branches before asking for confirmation.

Under the Producer's title, when its build pushed a catalog-info.yaml, the page shows the catalog context: the owner (team-orders (group)), the description, and a row of chips: the repository first, labelled by the host of its source location, then the Backstage links by their title. Below it, maintainers and administrators see the Webhooks card: signed POSTs for this Producer's events (new versions, rejected provides, deprecations, new Consumers, catalog pushes) with a delivery log per hook.

The spec viewer: history, diff and blame#

The viewer shows one document, or one endpoint of it, with its Version History down the side: every version of the line, its stability and provider, marked changed where the text differs from the version before. Pick two versions in Compare / Diff; switch Blame on to see, for every line, the version that last changed it. Copy and Download act on what is shown.

A diff has two switches. Ignore whitespace (off by default, per view) drops indentation and trailing-space changes; it exists for whole documents only, because endpoint snippets are re-serialised when a spec is split, so the endpoint view has no such switch. Unified / Side by side: side by side is the default on wide screens, the choice is remembered per browser, and screens narrower than 768 px always show unified. The same diff appears on the Producers page and in the admin dashboard.

Consumers#

/consumers.html lists every Consumer and the exact pins it holds: Producer, API type, version and endpoints. The catalog context block and the Webhooks card work as on the Producer page; a Consumer's hooks receive the events of every Producer the Consumer currently requires, and are managed by a maintainer of the Producer of the same name or by an administrator.

The dependency graph#

/graph.html renders the graph as an interactive SVG. The toolbar selects one of three views:

• Dev (default): the dev graph, everything ever provided or required, snapshots included.
• Main: the main graph, every Producer at its trunk version, edges from trunk pins.
• Branch: a sanshain-branch's pin set, what a release is.

All views share the focus filter (type a service name to spotlight its neighbourhood), the Circular layout, the protocol filters (OpenAPI, AsyncAPI, Proto), the Periphery switch for peripheral resources, and the Outdated and Snapshot-pinned highlights. A pin to a superseded snapshot counts as outdated, and hovering the edge says superseded by X ga.

Three switches shape the drawing itself and are remembered in the browser rather than in the URL: Vertical/Horizontal pivots the flow, and Compact tightens the gaps between nodes and ranks for an install whose graph has outgrown the screen, and Rainbow gives the plain arrows one colour per Consumer, so a caller's fan-out can be followed through the crossings; circular, missing, outdated and stale edges keep their warning colours.

Badges on a node show its protocols in the current view: solid badges on the top edge for what it provides (braces for REST, two-way arrows for gRPC, an envelope for messaging, a hexagon for a peripheral resource), outlined badges on the bottom edge for how it requires others. A harvested subscription to a channel nobody provides points at a dashed node named <channel> ?. Producers nobody requires and that require nothing sit as chips in one (unrequired) box beside the graph when it is taller than wide, below it otherwise, so the drawing squares up; the Unrequired switch hides the box (remembered in the URL as hide_protocols=unrequired).

Hovering a node opens its node panel: its version lines, what it provides and requires, and, below that, its catalog context with the owner, the description and the link chips, each opening in a new tab. A system without a catalog-info shows no such block.

The main view#

The main view surfaces what the dev view cannot see:

• Red edge: the pin lags the Producer's trunk version by a major.
• Amber dashed edge (stale): the pin was not refreshed since half the trunk TTL, a forgotten build about to age out.
• Orange dotted edge (dangling): the pinned version was deleted. It heals when the number is re-provided.
• Snapshot-pinned: the pin is served from an overwritable snapshot.

Branches, the timeline and compare#

Pick a branch in the toolbar to render its graph. The main and branch views carry a timeline slider whose markers are the instants the graph changed; drag it to see the graph as it was, and, with the releaser role, Create branch here cuts a branch at that instant. The Compare panel diffs any two selections, release against release or against main, either side optionally at a past instant, as services added or removed and pins added, removed or changed. Exports (SVG, PNG, mermaid) are stamped with view, branch and instant. The Release graphs chapter has the model behind these.

Reports#

/reports.html offers the Producer isolation report and the full dependency report (every provided and required endpoint with each dependency's pinned version). Both take a graph scope: dev, main or a sanshain-branch, the latter two optionally at an instant, so a release-scoped report describes what production is. The viewer copies the report as Markdown or downloads it. The same data is GET /report, /report/markdown and /report/isolation with ?scope=main[@instant] or ?scope=<branch>[@instant]; a read-only token may read them.

The audit timeline#

/audit.html is the audit timeline, every spec update and administrative action with a side-by-side diff, filtered by date, action, service or version wildcard and stream. It needs the view_audit permission, held by the admin and viewer roles: the link is hidden from everyone else and the data behind it is restricted. When a Producer's snapshot you pinned changed under you, someone with that permission can tell you who provided it.

Checked against v2.6.0.