Update HTTP REST API
272
HTTP-REST-API.md
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`
|
||||
- ` GET: /api/v1/get_config_value_by_name`
|
||||
- ` GET: /api/v1/get_directory_items`
|
||||
- ` GET: /api/v1/get_drive_information`
|
||||
- ` GET: /api/v1/get_open_files`
|
||||
- ` GET: /api/v1/get_pinned_files`
|
||||
- `POST: /api/v1/pin_file`
|
||||
- ` GET: /api/v1/pinned_status`
|
||||
- `POST: /api/v1/set_config_value_by_name`
|
||||
- `POST: /api/v1/unmount`
|
||||
- ` GET: /api/v1/unpin_file`
|
||||
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/`
|
||||
- **Auth:** HTTP Basic Auth on every request (checked by `rpc::check_authorization` before routing)
|
||||
- **Content-Type:** JSON for successful responses that include bodies; some endpoints return **no body** on success.
|
||||
- **Status Codes:**
|
||||
- `200 OK` on success
|
||||
- `401 Unauthorized` when Basic Auth fails (no JSON body is set by the handler)
|
||||
- `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_.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.
|
||||
|
||||
Reference in New Issue
Block a user