141 lines
2.7 KiB
Markdown
141 lines
2.7 KiB
Markdown
# HeroDB JSON-RPC Examples
|
|
|
|
These examples show full JSON-RPC 2.0 payloads for managing HeroDB via the RPC API (enable with `--enable-rpc`). Methods are named as `hero_<function>`. Params are positional arrays; enum values are strings (e.g., `"Redb"`). Copy-paste into Postman or similar clients.
|
|
|
|
## Database Management
|
|
|
|
### Create Database
|
|
Creates a new database with optional per-database encryption key (stored write-only in Admin DB 0).
|
|
|
|
```json
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"id": 1,
|
|
"method": "hero_createDatabase",
|
|
"params": [
|
|
"Redb",
|
|
{ "name": null, "storage_path": null, "max_size": null, "redis_version": null },
|
|
null
|
|
]
|
|
}
|
|
```
|
|
|
|
With encryption:
|
|
```json
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"id": 2,
|
|
"method": "hero_createDatabase",
|
|
"params": [
|
|
"Sled",
|
|
{ "name": "secure-db", "storage_path": null, "max_size": null, "redis_version": null },
|
|
"my-per-db-encryption-key"
|
|
]
|
|
}
|
|
```
|
|
|
|
### List Databases
|
|
Returns array of database infos (id, backend, encrypted status, size, etc.).
|
|
|
|
```json
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"id": 3,
|
|
"method": "hero_listDatabases",
|
|
"params": []
|
|
}
|
|
```
|
|
|
|
### Get Database Info
|
|
Retrieves detailed info for a specific database.
|
|
|
|
```json
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"id": 4,
|
|
"method": "hero_getDatabaseInfo",
|
|
"params": [1]
|
|
}
|
|
```
|
|
|
|
### Delete Database
|
|
Removes physical database file; metadata remains in Admin DB 0.
|
|
|
|
```json
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"id": 5,
|
|
"method": "hero_deleteDatabase",
|
|
"params": [1]
|
|
}
|
|
```
|
|
|
|
## Access Control
|
|
|
|
### Add Access Key
|
|
Adds a hashed access key for private databases. Permissions: `"read"` or `"readwrite"`.
|
|
|
|
```json
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"id": 6,
|
|
"method": "hero_addAccessKey",
|
|
"params": [2, "my-access-key", "readwrite"]
|
|
}
|
|
```
|
|
|
|
### List Access Keys
|
|
Returns array of key hashes, permissions, and creation timestamps.
|
|
|
|
```json
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"id": 7,
|
|
"method": "hero_listAccessKeys",
|
|
"params": [2]
|
|
}
|
|
```
|
|
|
|
### Delete Access Key
|
|
Removes key by its SHA-256 hash.
|
|
|
|
```json
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"id": 8,
|
|
"method": "hero_deleteAccessKey",
|
|
"params": [2, "0123abcd...keyhash..."]
|
|
}
|
|
```
|
|
|
|
### Set Database Public/Private
|
|
Toggles public access (default true). Private databases require access keys.
|
|
|
|
```json
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"id": 9,
|
|
"method": "hero_setDatabasePublic",
|
|
"params": [2, false]
|
|
}
|
|
```
|
|
|
|
## Server Info
|
|
|
|
### Get Server Stats
|
|
Returns stats like total databases and uptime.
|
|
|
|
```json
|
|
{
|
|
"jsonrpc": "2.0",
|
|
"id": 10,
|
|
"method": "hero_getServerStats",
|
|
"params": []
|
|
}
|
|
```
|
|
|
|
## Notes
|
|
- Per-database encryption keys are write-only; set at creation and used transparently.
|
|
- Access keys are hashed (SHA-256) for storage; provide plaintext in requests.
|
|
- Backend options: `"Redb"` (default) or `"Sled"`.
|
|
- Config object fields (name, storage_path, etc.) are optional and currently ignored but positional. |