BlockStorage/repertory
1
0
Fork 0
Code Issues 3 Pull Requests Releases 9 Wiki Activity

Update HTTP REST API

sgraves76
2025-08-13 20:41:15 -05:00
parent 90587cbb6b
commit 130cfadcd3
1 changed files with 260 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files

272
HTTP-REST-API.md

@@ -1,13 +1,261 @@
All `repertory` mounts expose an HTTP REST API. The following methods are available: # HTTP REST API (Repertory)
- ` GET: /api/v1/get_config` This document reflects the API **exactly as implemented** in the server code shown (`server` and `full_server`).
- ` GET: /api/v1/get_config_value_by_name`
- ` GET: /api/v1/get_directory_items` - **Bind Address:** `127.0.0.1`
- ` GET: /api/v1/get_drive_information` - **Base Path:** `/api/v1/`
- ` GET: /api/v1/get_open_files` - **Auth:** HTTP Basic Auth on every request (checked by `rpc::check_authorization` before routing)
- ` GET: /api/v1/get_pinned_files` - **Content-Type:** JSON for successful responses that include bodies; some endpoints return **no body** on success.
- `POST: /api/v1/pin_file` - **Status Codes:**
- ` GET: /api/v1/pinned_status` - `200 OK` on success
- `POST: /api/v1/set_config_value_by_name` - `401 Unauthorized` when Basic Auth fails (no JSON body is set by the handler)
- `POST: /api/v1/unmount` - `404 Not Found` for some resource misses (e.g., pin/unpin when path not found)
- ` GET: /api/v1/unpin_file` - `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_.get_api_port()`).
---
## Endpoints
### GET `/api/v1/get_config`
Return the full (cleaned) configuration JSON for the running mount.
- **Query params:** _none_
- **Response:** `200 OK` with JSON body (cleaned by `clean_json_config`); otherwise an error code.
- **Body (success):** JSON representing the current config.
**Example:**
```bash
curl -u USER:PASS "http://127.0.0.1:PORT/api/v1/get_config"
```
---
### GET `/api/v1/get_config_value_by_name`
Return a single configuration value by key.
- **Query params:**
- `name` (string, required) — key path, e.g. `S3Config.Bucket`
- **Response:** `200 OK` with JSON body; otherwise an error code.
- **Body (success):**
```json
{ "value": <clean_json_value> }
```
**Example:**
```bash
curl -u USER:PASS \
"http://127.0.0.1:PORT/api/v1/get_config_value_by_name?name=S3Config.Bucket"
```
---
### POST `/api/v1/set_config_value_by_name`
Set a single configuration value by key.
- **Form params (`application/x-www-form-urlencoded`):**
- `name` (string, required)
- `value` (string, required)
- **Response:** `200 OK` with JSON body; otherwise an error code.
- **Body (success):**
```json
{ "value": <clean_json_value> }
```
**Example:**
```bash
curl -u USER:PASS -X POST \
-d "name=HostConfig.ApiPort" \
-d "value=9981" \
"http://127.0.0.1:PORT/api/v1/set_config_value_by_name"
```
---
### POST `/api/v1/unmount`
Request a clean unmount of the running mount.
- **Params:** _none_
- **Response:** `200 OK` with **no body** on success (event `unmount_requested` is raised internally).
- **Body (success):** _empty_
**Example:**
```bash
curl -u USER:PASS -X POST "http://127.0.0.1:PORT/api/v1/unmount"
```
---
### GET `/api/v1/get_directory_items`
List items for a given directory path in the API namespace.
- **Query params:**
- `api_path` (string, required)
- **Response:** `200 OK` with JSON body; `404` if path not found is handled by lower layers, otherwise `500` on error.
- **Body (success):**
```json
{ "items": <fm_.get_directory_items(api_path)> }
```
**Example:**
```bash
curl -u USER:PASS \
"http://127.0.0.1:PORT/api/v1/get_directory_items?api_path=/"
```
---
### GET `/api/v1/get_drive_information`
Return mount/drive summary.
- **Query params:** _none_
- **Response:** `200 OK` with JSON body.
- **Body (success):**
```json
{
"cache_space_used": <bytes>,
"drive_space_total": <bytes>,
"drive_space_used": <bytes>,
"item_count": <integer>
}
```
**Example:**
```bash
curl -u USER:PASS "http://127.0.0.1:PORT/api/v1/get_drive_information"
```
---
### GET `/api/v1/get_open_files`
Return the set of currently open files tracked by the file manager.
- **Query params:** _none_
- **Response:** `200 OK` with JSON body.
- **Body (success):**
```json
{
"items": [
{ "path": "<api_path>", "count": <open_count> },
...
]
}
```
**Example:**
```bash
curl -u USER:PASS "http://127.0.0.1:PORT/api/v1/get_open_files"
```
---
### GET `/api/v1/get_pinned_files`
Return the set of currently pinned files.
- **Query params:** _none_
- **Response:** `200 OK` with JSON body.
- **Body (success):**
```json
{ "items": <provider_.get_pinned_files()> }
```
**Example:**
```bash
curl -u USER:PASS "http://127.0.0.1:PORT/api/v1/get_pinned_files"
```
---
### GET `/api/v1/pinned_status`
Return the pinned status for a single file.
- **Query params:**
- `api_path` (string, required)
- **Response:** `200 OK` with JSON body; `500` if provider query fails (internal error handling).
- **Body (success):**
```json
{ "pinned": true | false }
```
**Example:**
```bash
curl -u USER:PASS \
"http://127.0.0.1:PORT/api/v1/pinned_status?api_path=/media/movie.mkv"
```
---
### POST `/api/v1/pin_file`
Pin a file so it remains cached/available locally.
- **Form params (`application/x-www-form-urlencoded`):**
- `api_path` (string, required)
- **Response:** `200 OK` with **no body** if the file existed and was pinned; `404 Not Found` if the path is not a file; `500` on provider error.
- **Body (success):** _empty_
**Example:**
```bash
curl -u USER:PASS -X POST \
-d "api_path=/media/movie.mkv" \
"http://127.0.0.1:PORT/api/v1/pin_file"
```
---
### POST `/api/v1/unpin_file`
Unpin a file.
- **Form params (`application/x-www-form-urlencoded`):**
- `api_path` (string, required)
- **Response:** `200 OK` with **no body** if the file existed and was unpinned; `404 Not Found` if the path is not a file; `500` on provider error.
- **Body (success):** _empty_
**Example:**
```bash
curl -u USER:PASS -X POST \
-d "api_path=/media/movie.mkv" \
"http://127.0.0.1:PORT/api/v1/unpin_file"
```
---
## Authentication & Errors
- **Auth check** happens **before** routing; failed auth returns `401 Unauthorized` (no JSON body set in that path).
- **Exceptions** inside handlers return `500` with a JSON body:
```json
{
"path": "/api/v1/<method>",
"error": "<message or 'unknown error'>"
}
```
## Conventions & Notes
- `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.