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

Sanshain Service

Sanshain (Japanese for "sunshine") is a central repository that manages, splits and distributes API specifications: OpenAPI, AsyncAPI and gRPC/Proto.

A Producer publishes its full specification once. A Consumer does not take the whole document; it requires only the endpoints, channels or methods it actually calls, at the version it pins. The service keeps every version, tracks who depends on what, and rejects a publish that forgot its version bump or hides a breaking change behind a minor one, proposing the correct next version instead.

Producers and Consumers#

Producers provide their complete spec. Sanshain stores it as a new version in the Producer's version line and splits it into the endpoints, channels and methods it contains.

Consumers require only the snippets they use and receive a spec that holds nothing else. Each entry under requires in sanshain.yaml names the Producer, the exact version and the endpoints, channels or methods it uses, so a Consumer never ships with a dependency on an endpoint it does not call. A system is usually both.

Version lines#

A spec's version comes from the document itself (info.version; proto files use a // sanshain-version: comment) together with a declared stability:

snapshot — a version under development. Publishing the same snapshot number again replaces it.
ga — a released version. The number is claimed permanently and its content is immutable; only elements marked deprecated may be removed later.

A forgotten version bump, or a breaking change hiding behind a minor bump, is rejected at the door with the correct next version proposed. Consumers pin exact versions: no fallback, no surprises at build time.

The dependency graph#

Because every requirement is recorded, Sanshain knows exactly which Consumer pins which version of which endpoint. The dashboard draws that as a live graph of your services, highlighting Consumers that build against outdated versions or against snapshots. Release cuts, named branches and a timeline of past graph states turn the graph into a record of what production actually is.

Quick start#

With Docker:

docker run -p 3000:3000 -v sanshain-data:/data ghcr.io/paxel/sanshain-service:latest

From source (SQLite by default; migrations run on startup):

cargo run

Open http://localhost:3000/admin.html and log in as the initial admin (default root, see INITIAL_ADMIN_USERNAME) with the random password printed in the logs.
Change that password.
Run ./scripts/demo.sh to populate the service with sample Producers and Consumers.

The full walk-through, including PostgreSQL, the first API token and the first provide and require, is Getting started.

The documentation#

Four tracks, one per kind of reader. Press / to search across all of them.