From f69616b3a615439b05230dd534cbacee540ca5da Mon Sep 17 00:00:00 2001
From: "Scott E. Graves" <scott.e.graves@protonmail.com>
Date: Wed, 13 Aug 2025 20:55:20 -0500
Subject: [PATCH] Update HTTP REST API

---
 HTTP-REST-API.md | 42 ++++++++++++++++++++++++++++++++++++++----
 1 file changed, 38 insertions(+), 4 deletions(-)

diff --git a/HTTP-REST-API.md b/HTTP-REST-API.md
index a2808b3..3094689 100644
--- a/HTTP-REST-API.md
+++ b/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"
+```