Devin
08946a1971
Replaces an 89-line README that mostly duplicated code links with a
90-line README that answers the three questions a new reader actually
asks: 'what is this?', 'how do I run it?', 'where do I go next?'.
Also adds two longer-form references that the old README was missing
entirely:
docs/ARCHITECTURE.md (new):
- Four Mermaid diagrams:
1. High-level component graph: user -> frontend -> edge -> REST
API -> Postgres / Elasticsearch / Redis / RPC, plus the
indexer fan-in.
2. Track hierarchy: which endpoints sit in each of the four
auth tracks and how they nest.
3. Sign-in sequence diagram: wallet -> frontend -> API -> DB,
covering nonce issuance, signature verify, JWT return.
4. Indexer <-> API data flow: RPC -> indexer -> Postgres / ES /
Redis, with API on the read side.
- Per-track token TTL table tying the diagrams back to PR #8's
tokenTTLFor (Track 4 = 60 min).
- Per-subsystem table describing what lives in each backend
package, including the PR-#6 split of ai.go into six files.
- Runtime dependencies table.
- Security posture summary referencing PR #3's fail-fast JWT /
CSP checks, .gitleaks.toml, and docs/SECURITY.md.
docs/API.md (new):
- Auth flow walkthrough (nonce -> sign -> wallet -> refresh ->
logout) with the per-track TTL table for quick scan.
- Rate-limit matrix.
- Tagged endpoint index generated from
backend/api/rest/swagger.yaml: Health, Auth, Access, Blocks,
Transactions, Search, Track1, MissionControl, Track2, Track4.
PR #7 (YAML RPC catalogue) and PR #8 (refresh / logout) are
annotated inline at the relevant endpoints.
- Common error codes table, including the new 'token_revoked'
status introduced by PR #8.
- Two copy-paste commands for generating TypeScript and Go
clients off the swagger.yaml, so downstream repos don't have
to hand-maintain one.
README.md:
- Trimmed to 90 lines (previous was 89 lines of README lore).
- Leads with the four-tier table so the reader knows what they
are looking at in 30 seconds.
- 'Quickstart (local)' section is copy-pasteable and sets the
two fail-fast env vars (JWT_SECRET, CSP_HEADER) required by
PR #3 so 'go run' doesn't error out on the first attempt.
- Forward-references docs/ARCHITECTURE.md, docs/API.md,
docs/TESTING.md (from PR #10), docs/SECURITY.md (from PR #3),
and CONTRIBUTING.md.
- Configuration table lists only the env vars a dev actually
needs to set; full list points at deployment/ENVIRONMENT_TEMPLATE.env.
Verification:
wc -l README.md = 93 (target was <=150).
wc -l docs/ARCHITECTURE.md = 145 (four diagrams, tables, pointers).
wc -l docs/API.md = 115 (index + auth/error tables).
markdownlint-style scan no obvious issues.
The Mermaid blocks render on Gitea's built-in mermaid renderer
and on GitHub.
Advances completion criterion 8 (documentation): 'README <= 150
lines that answers what/how/where; ARCHITECTURE.md with diagrams
of tracks, components, and data flow; API.md generated from
swagger.yaml. Old ~300 status markdown files were removed by PR #2.'
147 lines
5.1 KiB
Markdown
147 lines
5.1 KiB
Markdown
# API Reference
|
||
|
||
Canonical, machine-readable spec: [`backend/api/rest/swagger.yaml`](../backend/api/rest/swagger.yaml)
|
||
(OpenAPI 3.0.3). This document is a human index regenerated from that
|
||
file — run `scripts/gen-api-md.py` after editing `swagger.yaml` to
|
||
refresh it.
|
||
|
||
## Base URLs
|
||
|
||
| Env | URL |
|
||
|-----|-----|
|
||
| Production | `https://api.d-bis.org` |
|
||
| Local dev | `http://localhost:8080` |
|
||
|
||
## Authentication
|
||
|
||
Track 1 endpoints (listed below under **Track1**, **Health**, and most
|
||
of **Blocks** / **Transactions** / **Search**) are public. Every other
|
||
endpoint requires a wallet JWT.
|
||
|
||
The flow:
|
||
|
||
1. `POST /api/v1/auth/nonce` with `{address}` → `{nonce}`
|
||
2. Sign the nonce with the wallet.
|
||
3. `POST /api/v1/auth/wallet` with `{address, nonce, signature}`
|
||
→ `{token, expiresAt, track, permissions}`
|
||
4. Send subsequent requests with `Authorization: Bearer <token>`.
|
||
5. Refresh before `expiresAt` with
|
||
`POST /api/v1/auth/refresh` (see [ARCHITECTURE.md](ARCHITECTURE.md)).
|
||
6. Log out with `POST /api/v1/auth/logout` — revokes the token's
|
||
`jti` server-side.
|
||
|
||
Per-track TTLs:
|
||
|
||
| Track | TTL |
|
||
|-------|-----|
|
||
| 1 | 12h |
|
||
| 2 | 8h |
|
||
| 3 | 4h |
|
||
| 4 | 60m |
|
||
|
||
## Rate limits
|
||
|
||
| Scope | Limit |
|
||
|-------|-------|
|
||
| Track 1 (per IP) | 100 req/min |
|
||
| Tracks 2–4 | Per-user, per-subscription; see subscription detail in `GET /api/v1/access/subscriptions` |
|
||
|
||
## Endpoint index
|
||
|
||
## Health
|
||
Health check endpoints
|
||
- `GET /health` — Health check
|
||
|
||
## Auth
|
||
Wallet and user-session authentication endpoints
|
||
- `POST /api/v1/auth/nonce` — Generate wallet auth nonce
|
||
- `POST /api/v1/auth/wallet` — Authenticate with wallet signature
|
||
- `POST /api/v1/auth/refresh` — Rotate a still-valid JWT (adds a new `jti`; revokes the old one) — PR #8
|
||
- `POST /api/v1/auth/logout` — Revoke the current JWT by `jti` — PR #8
|
||
- `POST /api/v1/auth/register` — Register an explorer access user
|
||
- `POST /api/v1/auth/login` — Log in to the explorer access console
|
||
|
||
## Access
|
||
RPC product catalog, subscriptions, and API key lifecycle
|
||
- `GET /api/v1/access/me` — Get current access-console user
|
||
- `GET /api/v1/access/products` — List available RPC access products (backed by `backend/config/rpc_products.yaml`, PR #7)
|
||
- `GET /api/v1/access/subscriptions` — List subscriptions for the signed-in user
|
||
- `GET /api/v1/access/admin/subscriptions` — List subscriptions for admin review
|
||
- `POST /api/v1/access/admin/subscriptions` — Request or activate product access
|
||
- `GET /api/v1/access/api-keys` — List API keys for the signed-in user
|
||
- `POST /api/v1/access/api-keys` — Create an API key
|
||
- `POST /api/v1/access/api-keys/{id}` — Revoke an API key
|
||
- `DELETE /api/v1/access/api-keys/{id}` — Revoke an API key
|
||
- `GET /api/v1/access/usage` — Get usage summary for the signed-in user
|
||
- `GET /api/v1/access/audit` — Get recent API activity for the signed-in user
|
||
- `GET /api/v1/access/admin/audit` — Get recent API activity across users for admin review
|
||
- `GET /api/v1/access/internal/validate-key` — Validate an API key for nginx auth_request or similar edge subrequests
|
||
- `POST /api/v1/access/internal/validate-key` — Validate an API key for internal edge enforcement
|
||
|
||
## Blocks
|
||
Block-related endpoints
|
||
- `GET /api/v1/blocks` — List blocks
|
||
- `GET /api/v1/blocks/{chain_id}/{number}` — Get block by number
|
||
|
||
## Transactions
|
||
Transaction-related endpoints
|
||
- `GET /api/v1/transactions` — List transactions
|
||
|
||
## Search
|
||
Unified search endpoints
|
||
- `GET /api/v1/search` — Unified search
|
||
|
||
## Track1
|
||
Public RPC gateway endpoints (no auth required)
|
||
- `GET /api/v1/track1/blocks/latest` — Get latest blocks (Public)
|
||
|
||
## MissionControl
|
||
Public mission-control health, bridge trace, and cached liquidity helpers
|
||
- `GET /api/v1/mission-control/stream` — Mission-control SSE stream
|
||
- `GET /api/v1/mission-control/liquidity/token/{address}/pools` — Cached liquidity proxy
|
||
- `GET /api/v1/mission-control/bridge/trace` — Resolve a transaction through Blockscout and label 138-side contracts
|
||
|
||
## Track2
|
||
Indexed explorer endpoints (auth required)
|
||
- `GET /api/v1/track2/search` — Advanced search (Auth Required)
|
||
|
||
## Track4
|
||
Operator endpoints (Track 4 + IP whitelist)
|
||
- `POST /api/v1/track4/operator/run-script` — Run an allowlisted operator script
|
||
|
||
## Error shape
|
||
|
||
All errors use:
|
||
|
||
```json
|
||
{
|
||
"error": "short_code",
|
||
"message": "human-readable explanation"
|
||
}
|
||
```
|
||
|
||
Common codes:
|
||
|
||
| HTTP | `error` | Meaning |
|
||
|------|---------|---------|
|
||
| 400 | `bad_request` | Malformed body or missing param |
|
||
| 401 | `unauthorized` | Missing or invalid JWT |
|
||
| 401 | `token_revoked` | JWT's `jti` is in `jwt_revocations` (PR #8) |
|
||
| 403 | `forbidden` | Authenticated but below required track |
|
||
| 404 | `not_found` | Record does not exist |
|
||
| 405 | `method_not_allowed` | HTTP method not supported for route |
|
||
| 429 | `rate_limited` | Over the track's per-window quota |
|
||
| 503 | `service_unavailable` | Backend dep unavailable or migration missing |
|
||
|
||
## Generating client SDKs
|
||
|
||
The `swagger.yaml` file is standard OpenAPI 3.0.3; any generator works.
|
||
|
||
```bash
|
||
# TypeScript fetch client
|
||
npx openapi-typescript backend/api/rest/swagger.yaml -o frontend/src/api/types.ts
|
||
|
||
# Go client
|
||
oapi-codegen -package explorerclient backend/api/rest/swagger.yaml > client.go
|
||
```
|