BlockStorage/repertory
1
0
Fork 0
Code Issues 4 Pull Requests Releases 8 Wiki Activity

Update HTTP REST API

Scott E. Graves
2025-08-13 20:55:20 -05:00
parent 161b3070c1
commit f69616b3a6
1 changed files with 38 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

42
HTTP-REST-API.md

@@ -4,7 +4,7 @@
The Repertory HTTP REST API uses hashed passwords for authentication.
Before making requests to any protected endpoint, hash your password using **BLAKE2b-384**, convert it to a hex string,
Before making requests to any protected endpoint, hash your password using **BLAKE2b-384**
and provide it according to the API's authentication requirements.
Example in C++:
@@ -20,7 +20,7 @@ Example hash for the password `repertory`:
55427d3dfdce97ef391db56aaf63a3726266777b46df1fa6dbc492093491e7605bd39cf6a88d6ccf4499b9d0de7f78c6
```
This document reflects the API **exactly as implemented** in the server code.
This document reflects the API **exactly as implemented** in the server code shown (`server` and `full_server`).
- **Bind Address:** `127.0.0.1`
- **Base Path:** `/api/v1/`
@@ -32,7 +32,7 @@ This document reflects the API **exactly as implemented** in the server code.
- `404 Not Found` for some resource misses (e.g., pin/unpin when path not found)
- `500 Internal Server Error` on unhandled exceptions (JSON body with `path` and `error` provided by exception handler)
> The server listens on `127.0.0.1:<API_PORT>`, where `<API_PORT>` comes from your runtime configuration (`config.json`).
> The server listens on `127.0.0.1:<API_PORT>`, where `<API_PORT>` comes from your runtime configuration (`config_.get_api_port()`).
---
@@ -276,6 +276,40 @@ curl -u USER:PASS -X POST \
## Conventions & Notes
- `api_path` is normalized before use.
- `api_path` is normalized via `utils::path::create_api_path` before use.
- Pin/unpin also raise events (`file_pinned` / `file_unpinned`) on success.
- `unmount` raises `unmount_requested` and returns immediately; actual unmount is asynchronous relative to the HTTP request.
---
## 🖥️ Example Usage with curl
### 1️⃣ Hash your password
The API requires the password to be hashed with **BLAKE2b-384** before sending.
Example in Linux/macOS (requires `b2sum` from coreutils):
```bash
echo -n "mypassword" | b2sum -l 384 | awk '{print $1}'
```
Example in Python:
```python
import hashlib
print(hashlib.blake2b(b"mypassword", digest_size=48).hexdigest())
```
### 2️⃣ Make an authenticated request
Example: List directory items in `/myfolder`
```bash
curl -u "repertory:$(echo -n 'mypassword' | b2sum -l 384 | awk '{print $1}')" "http://localhost:10000/api/v1/get_directory_items?api_path=/myfolder"
```
Example: Pin a file
```bash
curl -X POST -u "repertory:$(echo -n 'mypassword' | b2sum -l 384 | awk '{print $1}')" "http://localhost:10000/api/v1/pin_file?api_path=/docs/file1.txt"
```
Example: Unmount
```bash
curl -X POST -u "repertory:$(echo -n 'mypassword' | b2sum -l 384 | awk '{print $1}')" "http://localhost:10000/api/v1/unmount"
```