mirror of
https://github.com/block/buzz.git
synced 2026-11-03 07:51:22 +00:00
23f75dac90
Fill all 31 stub pages scaffolded in Phase 1 with content migrated and verified from the root docs, crate READMEs, and source code: - getting-started/ (3): installation, quickstart, local relay (TESTING.md) - architecture/ (8): ARCHITECTURE.md §1–§8, one page per section - guides/ (9): development, testing, agents, workflows, self-hosting, nostr-clients (operational half of NOSTR.md), adding-event-kinds, adding-api-endpoints, releasing - reference/ (5): CLI reference verified against buzz --help and crates/buzz-cli/src (18 groups / 87 subcommands; README drift noted), configuration, known-limitations (ARCHITECTURE §9 + conformance LIMITS.md + doc-debt list), NIPs index (13, NIP-CW canonical), design-docs index - vision/ (6): VISION.md + 5 VISION_*.md migrated with aspirational banners and rewritten links Root originals (ARCHITECTURE, NOSTR, TESTING, RELEASING, VISION*) get pointer notes marking docs/ as canonical; deletion is a follow-up. All relative links in the new tree verified to resolve. Known limitations are documented honestly, never papered over: rate limiting unenforced, WF-07/WF-08 workflow stubs, buzz-cli README drift, one-line GOVERNANCE.md. Note: pre-commit sadscan findings reviewed as false positives (dev-default postgres URI and NIP-OA test vectors, both already on origin/main). Co-authored-by: npub1pejagjwzjh7y36gq97hxf62ry75u3s6c6grr0rumx2p4c5qsms9s7jdtgl <0e65d449c295fc48e9002fae64e94327a9c8c358d206378f9b32835c5010dc0b@sprout-oss.stage.blox.sqprod.co> Signed-off-by: npub1pejagjwzjh7y36gq97hxf62ry75u3s6c6grr0rumx2p4c5qsms9s7jdtgl <0e65d449c295fc48e9002fae64e94327a9c8c358d206378f9b32835c5010dc0b@sprout-oss.stage.blox.sqprod.co>
33 lines
1.4 KiB
Markdown
33 lines
1.4 KiB
Markdown
# Adding a New API Endpoint
|
|
|
|
Prefer a signed Nostr event and the existing WebSocket/`POST /events` ingest
|
|
path over adding endpoint-specific JSON APIs. The relay intentionally exposes
|
|
only a narrow HTTP surface: NIP-11/NIP-05 metadata, `/events`, `/query`,
|
|
`/count`, `/hooks/{id}`, Blossom media, git smart HTTP, git policy hooks, and
|
|
health probes.
|
|
|
|
If an HTTP endpoint is still necessary:
|
|
|
|
1. **Define the handler** in the appropriate module under
|
|
`crates/buzz-relay/src/api/`. Resolve the request tenant before any auth or
|
|
data lookup, use NIP-98 when the endpoint accepts user credentials, and keep
|
|
community scoping explicit.
|
|
|
|
2. **Register the route** in `crates/buzz-relay/src/router.rs` using the
|
|
narrowest path possible. Do not add new `/api/*` compatibility routes unless
|
|
the product decision explicitly calls for one.
|
|
|
|
3. **Add database queries** in `buzz-db/src/` only when the endpoint cannot be
|
|
expressed through the existing event query paths.
|
|
|
|
4. **Handle errors** using the `api_error()`, `internal_error()`, and
|
|
`not_found()` helpers in `buzz-relay/src/api/mod.rs`. Return
|
|
`(StatusCode, Json<Value>)` tuples.
|
|
|
|
5. **Write tests** with the `buzz-test-client` harness in
|
|
`crates/buzz-test-client/tests/`, covering auth, community scoping, and the
|
|
relevant success path.
|
|
|
|
6. **Document** any public endpoint in `ARCHITECTURE.md` and user-facing docs.
|
|
|