adopted from the notes repo during the 2026-08-23 curation pass; project design/retro content lives with its project.

PDS-local API references #

ZDS (a PDS implementation in zig) exposes a local API reference at /api and an OpenAPI export at /api/openapi.json. This is swagger-like in the product sense: it gives a human-scannable reference for routes, methods, auth shape, rough inputs, and copyable curl examples. It is not currently Swagger UI, and it is not driven by a third-party OpenAPI renderer.

The important distinction is that this is a PDS-local reference. It answers:

• what HTTP operations this PDS instance implements
• which of those are XRPC methods
• what auth posture ZDS expects for each route
• what simple query/body/response fields we have documented so far
• what base URL should be used for examples on this deployment

That is different from the canonical Bluesky/ATProto docs, which answer what the protocol defines globally. A PDS-local reference can include custom routes, missing routes, implementation-specific admin surfaces, and deployment-specific example URLs.

What the current ZDS implementation is #

ZDS keeps a comptime-known endpoint inventory in src/http/router.zig. The same inventory powers:

• request routing
• /api
• /api/openapi.json
• tests that assert routes resolve as expected

This is intentionally not AST parsing and not runtime reflection. The server declares structured route metadata as Zig data. The docs renderer consumes that data, and the router loop consumes that data. Because both paths share the same inventory, adding or removing a route is less likely to leave docs stale.

The exploratory rendering lives under src/internal/api_reference/ so the PDS implementation can stay rigorous while the API-reference product grows. That space can absorb UI experiments, better OpenAPI generation, lexicon/schema joins, and maybe a future standalone library.

Other PDSs #

Among the PDS implementations checked locally:

• Tranquil has a strong explicit Axum route table and application/admin UI, but no discovered PDS-local endpoint reference or OpenAPI export.
• Cocoon has explicit Echo routes and a friendly root/info page, but no generated endpoint explorer.
• Pegasus has an admin dashboard and a very explicit Dream route list. Its Hermes library is the closest conceptual cousin because it generates XRPC client/server helpers from lexicons, but that is developer tooling rather than a live per-instance reference page.

So the ZDS category is: PDS-local API explorer generated from implemented server endpoint inventory.

Next directions #

• Join XRPC route metadata with lexicon definitions so query/body/response fields become real schemas rather than hand-written field-name lists.
• Keep OpenAPI output simple but valid. It can be useful even without adopting Swagger UI.
• Treat copyable request examples as first-class UI, not as incidental text.
• Consider HTMX only once the page needs server-rendered interactions. Search, filtering, and copy buttons are fine as tiny vanilla JavaScript.
• Keep the endpoint inventory close to routing until a better registration abstraction exists. The key property is one source of truth.