b3e8a9a058
Major additions: - Community Next.js app (port 18187) for browsing claims with API docs - stemedb-chaos crate: Fault injection, chaos testing, CRDT properties - Latent ingestion system: Reddit/FDA ingesters with ADK-Go agents - Disputed claims handling: Manual review workflows and validation - Aphoria security scanner: New extractors (SQL injection, command injection, weak crypto, TLS version), policy-based ignores, UAT reports - Docker infrastructure: Dockerfile, docker-compose.yml for full stack - VulnBank demo: Intentionally vulnerable multi-language test corpus SDK & API enhancements: - Source registry handlers for tracking data provenance - Metrics endpoint - Skeptic filtering improvements Code quality: - Split 14 large files (>500 lines) into focused modules - All files now under 500-line limit per project guidelines Documentation: - Chaos testing guide, circuit breakers, observability docs - Phase 7 UAT documentation updates - Martin Kleppmann technical writer agent Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
89 lines
4.3 KiB
Markdown
89 lines
4.3 KiB
Markdown
# API Surface
|
|
|
|
**Last Updated:** 2026-02-03
|
|
**Confidence:** High
|
|
|
|
## Summary
|
|
|
|
Episteme exposes an HTTP API via `axum` with auto-generated OpenAPI 3.1 documentation. The API is a thin layer that wires HTTP handlers to existing library crates (QueryEngine, Ingestor, VoteStore). Documentation is generated from the same Rust types used for serialization via `utoipa` derive macros.
|
|
|
|
**Key Facts:**
|
|
- Framework: `axum` with `utoipa-axum` for OpenAPI integration
|
|
- Crate: `stemedb-api`
|
|
- DTO layer converts between internal `rkyv` types and public `serde` JSON types
|
|
- OpenAPI 3.1 spec auto-generated at `/api-doc/openapi.json`
|
|
- Interactive docs via Swagger UI at `/swagger-ui` (dev mode)
|
|
- gRPC deferred; HTTP/JSON is the initial interface
|
|
|
|
**File Pointers:**
|
|
- `crates/stemedb-api/src/lib.rs` - App builder and OpenApiRouter
|
|
- `crates/stemedb-api/src/dto.rs` - Request/Response types (serde + ToSchema)
|
|
- `crates/stemedb-api/src/handlers/` - Route handlers
|
|
|
|
## Endpoints
|
|
|
|
| Method | Path | Description | Status |
|
|
|--------|------|-------------|--------|
|
|
| `POST` | `/v1/assert` | Submit signed assertion, writes to WAL | ✅ Implemented |
|
|
| `POST` | `/v1/epoch` | Create new epoch (paradigm) with content-addressed ID | ✅ Implemented |
|
|
| `POST` | `/v1/vote` | High-throughput vote submission | ✅ Implemented |
|
|
| `GET` | `/v1/query` | Resolve assertions via Lens | ✅ Implemented |
|
|
| `GET` | `/v1/skeptic` | Conflict analysis (Trust but Verify) | ✅ Implemented |
|
|
| `GET` | `/v1/health` | Service health check | ✅ Implemented |
|
|
| `GET` | `/v1/audit/queries` | List query audit trail | ✅ Implemented |
|
|
| `GET` | `/v1/audit/query/{id}` | Get specific query audit | ✅ Implemented |
|
|
| `GET` | `/v1/trace` | Trace assertion lineage | ✅ Implemented |
|
|
| `GET` | `/v1/meter/quota` | Check remaining quota | ✅ Implemented |
|
|
| `POST` | `/v1/meter/quota/limit` | Set custom quota limit (admin) | ✅ Implemented |
|
|
| `GET` | `/v1/admin/circuit-breaker/{agent_id}` | Get circuit breaker status | ✅ Implemented |
|
|
| `POST` | `/v1/admin/circuit-breaker/reset` | Manually reset a circuit | ✅ Implemented |
|
|
| `GET` | `/v1/admin/circuit-breakers/tripped` | List all Open/HalfOpen circuits | ✅ Implemented |
|
|
| `GET` | `/metrics` | Prometheus metrics (Phase 8B) | ✅ Implemented |
|
|
| `GET` | `/api-docs/openapi.json` | OpenAPI 3.1 spec | ✅ Implemented |
|
|
| `GET` | `/swagger-ui` | Interactive API docs | ✅ Implemented |
|
|
| `POST` | `/v1/sources` | Register source with human-readable metadata | ✅ Implemented |
|
|
| `GET` | `/v1/sources/{hash}` | Get source record by hash | ✅ Implemented |
|
|
| `PATCH` | `/v1/sources/{hash}/status` | Update source status (deprecate/quarantine) | ✅ Implemented |
|
|
| `GET` | `/v1/sources` | List/search sources (filter by tier or query) | ✅ Implemented |
|
|
|
|
### Cluster Gateway Endpoints (stemedb-cluster)
|
|
|
|
| Method | Path | Description | Status |
|
|
|--------|------|-------------|--------|
|
|
| `POST` | `/v1/assert` | Routed assertion to shard leader | ✅ Implemented |
|
|
| `GET` | `/v1/query` | Routed query to shard replica | ✅ Implemented |
|
|
| `POST` | `/v1/vote` | Routed vote to shard leader | ✅ Implemented |
|
|
| `GET` | `/v1/health` | Gateway health check | ✅ Implemented |
|
|
| `GET` | `/v1/cluster/status` | Cluster and node status | ✅ Implemented |
|
|
| `GET` | `/v1/shards/{shard_id}` | Shard descriptor details | ✅ Implemented |
|
|
| `GET` | `/v1/route` | Test subject routing | ✅ Implemented |
|
|
| `GET` | `/v1/admin/cluster` | Cluster status (alias) | ✅ Implemented |
|
|
| `GET` | `/v1/admin/ranges` | All shard/range assignments | ✅ Implemented |
|
|
| `POST` | `/v1/admin/sync` | Force anti-entropy sync | ✅ Implemented |
|
|
| `GET` | `/metrics` | Prometheus metrics (Phase 8B) | ✅ Implemented |
|
|
|
|
## DRY Type Pipeline
|
|
|
|
```
|
|
stemedb-core types (rkyv) ← Internal storage format
|
|
|
|
|
| impl From<> / Into<>
|
|
v
|
|
stemedb-api DTOs (serde + ToSchema) ← Public API contract
|
|
|
|
|
| utoipa derive macros
|
|
v
|
|
OpenAPI 3.1 JSON ← Auto-generated spec
|
|
|
|
|
| Widdershins (CI)
|
|
v
|
|
Slate markdown ← Published docs
|
|
```
|
|
|
|
## Related Topics
|
|
|
|
- [Storage](./storage.md) - KV layout and write path
|
|
- [Lens](./lens.md) - Read-time resolution strategies
|
|
- [Observability](../features/observability.md) - Prometheus metrics and admin endpoints
|
|
- [API Documentation Pattern](../patterns/api-documentation.md) - Toolchain details
|