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. 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. and provide it according to the API's authentication requirements.
Example in C++: Example in C++:
@@ -20,7 +20,7 @@ Example hash for the password `repertory`:
55427d3dfdce97ef391db56aaf63a3726266777b46df1fa6dbc492093491e7605bd39cf6a88d6ccf4499b9d0de7f78c6 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` - **Bind Address:** `127.0.0.1`
- **Base Path:** `/api/v1/` - **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) - `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) - `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 ## 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. - 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. - `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"
```