802256f929
Execute WIKI-UPDATE-PLAN.md (14 items): - NEW docs/PRINTER-INSTALLER.md: install-list / pc-default / install-batch contract + public installer map page. - NEW-shape docs/API-REFERENCE.md: index + pointer to the live generated docs (/api/docs Redoc, openapi.json, llms.txt, MCP), replacing a stale full dump. - geenforce cutover + GE-ENFORCE-DISPLAY/CLIENT/DEPLOY: server-first display dispatcher (display-role by FQDN, display-type.txt fallback), dashboarddefaults FQDN keying, legacy kiosk autostart self-heal (Wow6432Node), per-PC-type cutover status. - PLUGINS: printers/slides rows + plugin-permissions note (slides.manage). - IMPORT-API: dashboarddefaults FQDN-first keying. - CONFIG: word-wise search, site_timezone setting. - PILOT-DEPLOY: servers-to-network reclassify step. IMPORT-ADOPTION: fixup note. - CLAUDE.md: test count 1077->1159, HTTPS-cutover state. CHANGELOG: timezone + kiosk-autostart fixes, site_timezone setting.
134 lines
8.4 KiB
Markdown
134 lines
8.4 KiB
Markdown
# API reference (index)
|
|
|
|
This page is an index and a pointer, not a full specification. It answers three
|
|
questions: what endpoints exist, who calls them, and what auth they require. The
|
|
detailed request and response shapes live in the live generated docs and in the
|
|
per-surface contract docs linked from each table below.
|
|
|
|
## Live and generated docs
|
|
|
|
The repo ships hosted, generated API docs. Start there:
|
|
|
|
- **Interactive spec:** `GET /api/docs` - a self-hosted Redoc page over the
|
|
generated OpenAPI spec. The Redoc bundle is vendored under
|
|
`shopdb/core/api/staticdocs/`, so it renders fully offline on the air-gapped
|
|
prod box (no CDN).
|
|
- **Raw spec:** `GET /api/docs/openapi.json` - OpenAPI 3.1, roughly 238 paths and
|
|
362 operations. Generated by `scripts/gen_openapi.py` from
|
|
`docs/api-inventory.json`; regenerate after any API change.
|
|
- **LLM / agent entry point:** `GET /api/docs/llms.txt` - a concise API guide
|
|
following the llms.txt convention, plus a read-only MCP server
|
|
(`mcp/shopdb_mcp.py`, built with `FastMCP.from_openapi` over the same spec).
|
|
The MCP server exposes a curated set of GET endpoints as tools for an agent to
|
|
query the asset database over HTTPS with a scoped read token; it never runs on
|
|
the prod box. Set it up on a work PC with
|
|
`pxe-images/github/setup-mcp.cmd`.
|
|
|
|
The docs blueprint is `shopdb/core/api/docs.py` (a core blueprint, always
|
|
mounted regardless of which plugins are staged into a site build).
|
|
|
|
Contract docs (linked per table below) hold the deep semantics: field mappings,
|
|
idempotency rules, rotation, error envelopes, staged rollout. This page only
|
|
routes you to the right one.
|
|
|
|
---
|
|
|
|
## 1. Fleet and client contracts (unauthenticated or token)
|
|
|
|
These are the endpoints the shopfloor PC fleet, kiosks, displays, and printer
|
|
installers call. They are consumed by machines, not by the interactive UI, and
|
|
they authenticate with a scoped service token or nothing at all.
|
|
|
|
| Endpoint | Auth | Purpose | Contract doc |
|
|
|---|---|---|---|
|
|
| `GET /api/geenforce/manifest?pctype=<scope>` | `geenforce.fetch` service token (`X-API-Key` or Bearer PAT) | Serve the current published manifest for a PC-type scope. ETag / 304 supported. | GE-ENFORCE-CLIENT.md, geenforce-api-cutover.md |
|
|
| `GET /api/geenforce/payload/<sha256>` | `geenforce.fetch` service token | Serve a payload blob (installer) by content hash so share-less PCs pull over HTTPS instead of SMB. Rate limited and size capped; the sha256 is the integrity guarantee. | GE-ENFORCE-CLIENT.md, geenforce-api-cutover.md |
|
|
| `POST /api/geenforce/report` | `geenforce.report` service token | Record one PC's enforcement cycle: applied manifest version plus per-entry self-heal outcomes. | GE-ENFORCE-CLIENT.md, geenforce-api-cutover.md |
|
|
| `POST /api/collector/<plugin>` | `X-API-Key` env key or a `collector.ingest` managed token | Generic idempotent inventory upsert; the PC fleet targets `/api/collector/computers`. | COLLECTOR-INTEGRATION.md |
|
|
| `POST /api/collector/pc`, `/apps`, `/heartbeat`, `/bulk` | `X-API-Key` or `collector.ingest` token | Legacy computers-only collector paths (predate ADR-006); deprecated in favor of `/api/collector/computers`. | COLLECTOR-INTEGRATION.md |
|
|
| `GET /api/collector/status` | `X-API-Key` or `collector.ingest` token | Collector liveness and endpoint list. | COLLECTOR-INTEGRATION.md |
|
|
| `GET /api/printers/install-list` | optional JWT (anonymous fleet or logged-in browser) | Flat list of network printers with floor-map positions for the signed installer. `?format=text` returns a pipe-delimited variant. | PRINTER-INSTALLER.md |
|
|
| `GET /api/printers/pc-default?machine=NNNN` | optional JWT | The PC's default printer by machine (asset) number, via the `defaultprinter` relationship. `?format=text` supported. | PRINTER-INSTALLER.md |
|
|
| `GET /api/printers/install-batch?printerids=1,2,3` | optional JWT | Generate a self-deleting Windows `.bat` that installs the selected printers. | PRINTER-INSTALLER.md |
|
|
| `GET /api/dashboarddefaults/display-role?fqdn=<fqdn>` | public (none) | Resolve what a display PC should show (role `dashboard`/`lobby`/`partskiosk`, frontend path, business unit). FQDN-first, IP fallback. | GE-ENFORCE-DISPLAY.md |
|
|
| `GET /api/dashboarddefaults/visitor-location?fqdn=<fqdn>` | public (none) | Resolve the business unit for a lobby display by FQDN (IP fallback). | GE-ENFORCE-DISPLAY.md |
|
|
|
|
The `geenforce.fetch` and `geenforce.report` scopes accept both `X-API-Key` and
|
|
`Authorization: Bearer` transports, the same managed-token pattern the collector
|
|
uses (see COLLECTOR-INTEGRATION.md for how to mint, deploy, and rotate a scoped
|
|
token). A fetch token may be further resource-bound to specific scopes; a bound
|
|
token is denied (403 on manifest, 404 on payload) anything outside its scopes.
|
|
|
|
---
|
|
|
|
## 2. Import API
|
|
|
|
The import surface (an admin PAT plus `X-Import-Mode` to preserve legacy
|
|
timestamps) lets a script load an entire legacy database through the same
|
|
endpoints the UI uses. It is documented in full, per resource, in **IMPORT-API.md**
|
|
and is not duplicated here. The dashboarddefaults import fields (FQDN-preferred
|
|
keying) are covered there as well.
|
|
|
|
---
|
|
|
|
## 3. Core UI API
|
|
|
|
Everything else is the core UI API: the endpoints the Vue frontend calls. As a
|
|
rule these are JWT-authenticated (a login token or a managed Personal Access
|
|
Token) and versioned by the plugin contract (`__contract_version__`, currently
|
|
0.15.0). Behavior and stability guarantees are in **CONTRACT-STABILITY.md**;
|
|
sister sites should pin tight `core_version` ranges until the contract reaches
|
|
1.0.
|
|
|
|
Two auth patterns dominate the reads:
|
|
|
|
- **Public (no token ever).** The endpoints below are reachable with no
|
|
credential at all. This is the surface a firewall or deployment reviewer asks
|
|
about, so it is enumerated in full.
|
|
- **Optional JWT (`jwt_required(optional=True)`).** Nearly every core and plugin
|
|
GET (list / detail / report / dashboard-summary) is optional-auth: it serves
|
|
reads anonymously and only requires a JWT for writes. There are well over a
|
|
hundred of these; rather than reprint them, enumerate them from the live spec
|
|
at `/api/docs` (filter to the `GET` operations). All product reports
|
|
(`/api/reports/*` and every plugin `.../report*`) are optional-auth by the same
|
|
convention.
|
|
|
|
Every mutating endpoint (POST / PUT / PATCH / DELETE) requires a JWT and is
|
|
gated by `require_role` or `require_permission`; none are public.
|
|
|
|
### Fully public endpoints (auth = none)
|
|
|
|
| Endpoint | Purpose |
|
|
|---|---|
|
|
| `POST /api/auth/login` | Obtain a JWT. |
|
|
| `GET /api/setup/needs-admin` | First-run check: does the instance have zero users. |
|
|
| `POST /api/setup/create-admin` | First-run only; creates the first admin, then 403s forever. |
|
|
| `GET /api/settings/map-blueprint/<filename>` | Serve the floor-map blueprint image. |
|
|
| `GET /api/settings/branding/<filename>` | Serve site branding assets (logo, etc.). |
|
|
| `GET /api/models/image/<filename>` | Serve a model image. |
|
|
| `GET /api/dashboard/navigation` | Public navigation tree. |
|
|
| `GET /api/dashboard/health` | Liveness / health probe. |
|
|
| `GET /api/plugins/enabled` | List enabled plugins (no claims used). |
|
|
| `GET /api/dashboarddefaults/display-role` | Display role resolution (see section 1). |
|
|
| `GET /api/dashboarddefaults/visitor-location` | Lobby business-unit resolution (see section 1). |
|
|
| `GET /api/employees/search`, `/lookup/<sso>`, `/lookup` | Employee directory lookups (kiosk / sign-in flows). |
|
|
| `GET /api/employees/photo/<filename>` | Serve an employee photo. |
|
|
| `GET /api/notifications` (and `/types`, `/<id>`, `/active`, `/calendar`, `/dashboard/summary`, `/employee/<sso>`, `/shopfloor`) | Read shop-floor notifications for the public display and kiosks. |
|
|
| `GET /api/slides/feed` | Slide feed for the lobby display and screensaver. |
|
|
| `GET /api/slides/img/<surface>/<filename>` | Serve a slide image. |
|
|
| `GET /api/printedparts/image/<filename>` | Serve a printed-part image. |
|
|
| `GET /api/printedparts/kiosk/item/<itemcode>` | Kiosk part lookup (deliberately open; a kiosk carries no JWT). |
|
|
| `POST /api/printedparts/kiosk/take` | Kiosk part checkout (deliberately open, per decision record). |
|
|
|
|
---
|
|
|
|
## See also
|
|
|
|
- `docs/adr/README.md` - architecture decision records index.
|
|
- `docs/DEPLOY.md` - deployment; the public-endpoint inventory in section 3 above
|
|
is the site-exposure surface a deploy reviewer needs.
|
|
- `docs/PLUGINS.md` - the plugin catalog.
|
|
- Contract docs: GE-ENFORCE-CLIENT.md, geenforce-api-cutover.md,
|
|
COLLECTOR-INTEGRATION.md, PRINTER-INSTALLER.md, GE-ENFORCE-DISPLAY.md,
|
|
IMPORT-API.md, CONTRACT-STABILITY.md.
|