mirror of
https://github.com/bitcoinresearchkit/brk.git
synced 2026-07-02 06:48:59 -07:00
nym21
110 lines
3.6 KiB
Markdown
110 lines
3.6 KiB
Markdown
# brk_server
|
|
|
|
HTTP server providing REST API access to Bitcoin analytics data. Serves computed datasets from brk_indexer and brk_computer with multiple output formats, caching, and optional web interfaces.
|
|
|
|
## Overview
|
|
|
|
**Core Features**:
|
|
- **REST API**: Vector-based data access with pagination and format options
|
|
- **Multiple Formats**: JSON, CSV, TSV, Markdown output
|
|
- **HTTP Caching**: ETag-based caching with compression (Brotli, Gzip, Zstd, Deflate)
|
|
- **Weight Limits**: Request size protection (max 320,000 weight units)
|
|
- **Web Interface**: Optional website serving
|
|
|
|
**Port**: Auto-assigns starting from 3110
|
|
|
|
## API Reference
|
|
|
|
### Vector Metadata
|
|
|
|
| Endpoint | Description |
|
|
|----------|-------------|
|
|
| `GET /api/vecs/index-count` | Total number of available indexes |
|
|
| `GET /api/vecs/id-count` | Total number of vector IDs |
|
|
| `GET /api/vecs/vec-count` | Total number of vectors (sum of all index/ID combinations) |
|
|
| `GET /api/vecs/indexes` | List of all available indexes |
|
|
| `GET /api/vecs/accepted-indexes` | Object mapping indexes to their accepted variants |
|
|
| `GET /api/vecs/ids?page=N` | Paginated list of vector IDs (1000 per page, default page=0) |
|
|
| `GET /api/vecs/index-to-ids?index=INDEX&page=N` | Vector IDs supporting given index |
|
|
| `GET /api/vecs/id-to-indexes?id=ID` | Indexes supported by given vector ID |
|
|
|
|
### Vector Data Access
|
|
|
|
#### Direct Access Pattern: `GET /api/vecs/{INDEX}-to-{ID}`
|
|
|
|
Access single vector with index-to-id pattern (dashes replaced with underscores internally).
|
|
|
|
**Query Parameters:**
|
|
- `from` (i64, optional): Inclusive start index. Negative values count from end (default: 0)
|
|
- `to` (i64, optional): Exclusive end index. Negative values count from end. Overrides `count`
|
|
- `count` (usize, optional): Number of values to retrieve
|
|
- `format` (string, optional): Output format - `json`, `csv`, `tsv`, `md` (default: `json`)
|
|
|
|
**Examples:**
|
|
```bash
|
|
# Latest 100 price closes
|
|
curl /api/vecs/date-to-close?from=-100
|
|
|
|
# First 50 values as CSV
|
|
curl /api/vecs/height-to-difficulty?count=50&format=csv
|
|
|
|
# Range from index 1000 to 1999
|
|
curl /api/vecs/date-to-volume?from=1000&to=2000
|
|
```
|
|
|
|
#### Multi-Vector Query: `GET /api/vecs/query`
|
|
|
|
Query multiple vectors simultaneously with flexible output formats.
|
|
|
|
**Required Parameters:**
|
|
- `index`: Vector index type
|
|
- `ids`: Comma or space-separated vector IDs
|
|
|
|
**Optional Parameters:**
|
|
- `from`, `to`, `count`, `format`: Same as direct access
|
|
|
|
**Response Types:**
|
|
- **Single value**: One vector, one result (e.g., `from=-1`)
|
|
- **Array**: One vector, multiple results
|
|
- **Matrix**: Multiple vectors (always matrix, even for single results)
|
|
|
|
**Examples:**
|
|
```bash
|
|
# Single vector, latest value
|
|
curl '/api/vecs/query?index=date&ids=close&from=-1'
|
|
|
|
# Multiple vectors, date range
|
|
curl '/api/vecs/query?index=date&ids=open,high,low,close&from=-30&format=csv'
|
|
|
|
# Complex multi-vector query
|
|
curl '/api/vecs/query?index=week&ids=price-usd,volume,difficulty&count=52'
|
|
```
|
|
|
|
### System Endpoints
|
|
|
|
| Endpoint | Description |
|
|
|----------|-------------|
|
|
| `GET /version` | Server version (JSON string) |
|
|
| `GET /health` | Health check with timestamp |
|
|
| `GET /api` | Redirects to this documentation |
|
|
| `GET /*` | Static file serving (when website enabled) |
|
|
|
|
### HTTP Features
|
|
|
|
**Caching:**
|
|
- ETag-based conditional requests (304 Not Modified)
|
|
- `Cache-Control: must-revalidate` headers
|
|
- In-memory cache with 50ms guard timeout
|
|
|
|
**Compression:**
|
|
- Brotli, Gzip, Zstd, Deflate support
|
|
- Automatic content encoding negotiation
|
|
|
|
**CORS:**
|
|
- Cross-origin requests enabled
|
|
- Appropriate headers for web client access
|
|
|
|
**Rate Limiting:**
|
|
- Request weight system (max 320,000 units)
|
|
- Weight calculated from data range size
|