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>
4.3 KiB
4.3 KiB
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:
axumwithutoipa-axumfor OpenAPI integration - Crate:
stemedb-api - DTO layer converts between internal
rkyvtypes and publicserdeJSON 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 OpenApiRoutercrates/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 - KV layout and write path
- Lens - Read-time resolution strategies
- Observability - Prometheus metrics and admin endpoints
- API Documentation Pattern - Toolchain details