From b8671635cd891068afee81fde05bed880124ec85 Mon Sep 17 00:00:00 2001 From: Christophe Besson Date: Mon, 5 Oct 2026 10:36:18 +0200 Subject: docs: generate an HTTP API listing for the hub and the node control API MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit docs/MESHBAY_HTTP_API.md lists every route of the hub (by domain, with the authentication each requires) and of the node's loopback control API. It is written by docs/generate_http_api.py from the routes and their docstrings; test_http_api_doc.py fails when the file drifts from the code or when a route has no docstring, so a new route must say what it does. 79 routes had no docstring and get a one-line description; a few whose first line did not describe the route get a summary line. The login page's developer docs gain an API link next to Design and Protocol, in every language. README, MESHBAY_DESIGN.md (§0.1, §6.7, §7) and CLAUDE.md point to the listing; README also points to examples/. The examples scripts with a shebang become executable. Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) (limited to 'CLAUDE.md') diff --git a/CLAUDE.md b/CLAUDE.md index 6845b5f..2f3353f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -9,8 +9,11 @@ music, photos). It is not a public file-sharing network; public groups are an optional hub feature and are off on the reference deployment. **`docs/MESHBAY_DESIGN.md` is the architecture specification.** -`docs/MESHBAY_NODE_PROTOCOL.md` is the wire format. Everything else under -`docs/` is either an operational guide, or a superseded document kept for its +`docs/MESHBAY_NODE_PROTOCOL.md` is the wire format. `docs/MESHBAY_HTTP_API.md` +lists every route of the hub and of the node's control API; it is **generated** +by `docs/generate_http_api.py` from the routes and their docstrings, never edited +by hand, and `test_http_api_doc.py` fails when it drifts or when a route has no +docstring. Everything else under `docs/` is either an operational guide, or a superseded document kept for its cross-references and carrying a banner that says so. **`docs/QUICKSTART.md` and `docs/USERGUIDE.md` are the user documentation** — @@ -203,6 +206,7 @@ that produced it. | Cryptography, key hierarchy, the group and chat envelopes | §4 | | The protocol: handshake, authorization, signed ops, leases, versioning | §5, and `docs/MESHBAY_NODE_PROTOCOL.md` for the wire format | | The node, the hub, the clients, the applications | §6, §7, §8, §9 | +| Every HTTP route, hub and node control API | `docs/MESHBAY_HTTP_API.md` (generated) | | Structural decisions that are not revisited | §14 | | What is built, what is not, what is open | §15 | | A reference to a document that no longer exists (`draft-v5 §5.2`, `apps.md §3`, …) — in git history, or in a document outside this repository | §16, the concordance — it maps every one onto its replacement section. The code itself cites `MESHBAY_DESIGN.md` and a section directly | -- cgit v1.2.3