# API-Spine

> The machine-readable spine (OpenAPI) behind this website's facades.

## What it does {#was}

The API spine is the one typed core behind the facades: the REST specification is emitted from code, the client is generated from the specification, and the MCP tool surface binds to the same functions — never a second implementation of the same semantics. Fourteen operations, each mapped to exactly one row of a capability register that lives in code; a test proves register and specification cover each other exactly rather than asserting it in prose. The data source in this phase is the registry repository itself, strictly read-only: there is no write path in the code, and /directory serves zero entries today. On every commit four comparisons run between what the code emits and what is committed — specification, generated client, RFC 9728 metadata and the tool inventory; any difference stops the commit. What the spine does not do: serve anything outwards — oh-api serve binds to 127.0.0.1, and the website builds its facades statically and never calls it; what they share is the schema, not the process.


## Run it yourself {#betreiben}

**You need:**

- Rust (stable via rustup) and Git; every command runs from the root of the corpus checkout.

From the root of the corpus checkout, line by line:

```bash
cargo run --locked --manifest-path registry/api/spine/Cargo.toml -- serve --root . --port 8710
```

Then you should see:

```text
oh-api serving on 127.0.0.1:8710
```

## Test {#testen}

```bash
cargo test --locked --manifest-path registry/api/spine/Cargo.toml
```
- Runs without network: every answer comes from the repository, the result is the same every run.

## Call {#ansteuern}

- **Public:** *not yet* — No public endpoint: zone, route and deployment are not switched on.
- **Local:** http://127.0.0.1:8710

### Contracts

- **OpenAPI 3.0.3** `registry/api/openapi.json`
- **Generated client** `registry/api/client`

### The capability register

```bash
curl -s http://127.0.0.1:8710/capabilities
```

Response (excerpt):

```json
[{"id":"meta.capabilities","operation_id":"get_capabilities","method":"GET","path":"/capabilities","summary":"The machine-readable capability register with published client coverage", …}, … 14 rows]
```

### Usage and options

```text
usage: oh-api emit-openapi | serve --root <dir> [--port <n>]
```

## Contribute {#mitwirken}

Changes go through merge requests and the same gates as the association's own: formatting, Clippy without warnings, tests, seal and drift checks. Security reports, in confidence, to admin@openhelvetia.swiss.

The base tier costs nothing; what the operation lives on is under [About us, Financing](../../../about/financing/index.html).

## Module card {#steckbrief}

State, evidence, download and dependencies are on the infrastructure page: [API-Spine](../../../directory/building-blocks/api-spine/index.html).

---

Source: generated from public/web/modules.json