mirror of https://github.com/block/buzz.git synced 2026-08-18 06:50:31 +02:00

Files

T

npub1pejagjwzjh7y36gq97hxf62ry75u3s6c6grr0rumx2p4c5qsms9s7jdtgl 23f75dac90 docs: write full documentation content (Phase 2)

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>

2026-07-07 12:14:33 -07:00

1.4 KiB

Raw Blame History

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:

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.
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.
Add database queries in buzz-db/src/ only when the endpoint cannot be expressed through the existing event query paths.
Handle errors using the api_error(), internal_error(), and not_found() helpers in buzz-relay/src/api/mod.rs. Return (StatusCode, Json<Value>) tuples.
Write tests with the buzz-test-client harness in crates/buzz-test-client/tests/, covering auth, community scoping, and the relevant success path.
Document any public endpoint in ARCHITECTURE.md and user-facing docs.

1.4 KiB Raw Blame History

Adding a New API Endpoint

1.4 KiB

Raw Blame History