Documentation for v2.9.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. A Documentation card links these pages for the release the instance runs (…/sanshain-service/v<version>/), so what you read matches what it does.

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.
• the origin when the providing build sent one: the note, then chips for the build, the change (pull or merge request) and each ticket, the tickets linked through the ticket URL template an administrator set.

Expanding a row lists the endpoints of that version, each with the one line the Producer wrote about it (an OpenAPI summary or the first sentence of its description, a message summary, the comment above a proto rpc), 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, and, where the providing build said so, why: the diff header and every blame block carry the version's origin. 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, or tag:<name> for every system whose catalog carries the tag), 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, 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), and Topics draws every AsyncAPI channel as a node of its own, publishers pointing at it and subscribers hanging off it, in place of the direct messaging arrows; a channel nobody publishes is a dashed topic, and the topic's panel lists its publishers and subscribers.

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).

Resting the mouse on a node for two seconds opens its node panel: its version lines, what it provides and requires, and, below that, its catalog context with the owner, the description, the link chips, each opening in a new tab, and the tag chips. 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.