From f39942a88b446035f54602090463bfc24fd5c28f Mon Sep 17 00:00:00 2001 From: elibosley <11823237+elibosley@users.noreply.github.com> Date: Tue, 11 Feb 2025 20:57:09 +0000 Subject: [PATCH] docs: update API documentation --- docs/API/_category_.json | 4 + docs/API/cli.md | 161 ++++++++++++++++++++++++++ docs/API/how-to-use-the-api.md | 202 +++++++++++++++++++++++++++++++++ docs/API/index.md | 35 ++++++ docs/API/upcoming-features.md | 69 +++++++++++ 5 files changed, 471 insertions(+) create mode 100644 docs/API/_category_.json create mode 100644 docs/API/cli.md create mode 100644 docs/API/how-to-use-the-api.md create mode 100644 docs/API/index.md create mode 100644 docs/API/upcoming-features.md diff --git a/docs/API/_category_.json b/docs/API/_category_.json new file mode 100644 index 000000000..1e4ded6ca --- /dev/null +++ b/docs/API/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Unraid API", + "position": 4 +} \ No newline at end of file diff --git a/docs/API/cli.md b/docs/API/cli.md new file mode 100644 index 000000000..edec10162 --- /dev/null +++ b/docs/API/cli.md @@ -0,0 +1,161 @@ +# CLI Commands + +### Start + +```bash +unraid-api start [--log-level ] +``` + +Starts the Unraid API service. + +- `--log-level`: Optional. Set logging level (trace|debug|info|warn|error) + +### Stop + +```bash +unraid-api stop [--delete] +``` + +Stops the Unraid API service. + +- `--delete`: Optional. Delete the PM2 home directory + +### Restart + +```bash +unraid-api restart +``` + +Restarts the Unraid API service. + +### Logs + +```bash +unraid-api logs [-l ] +``` + +View the API logs. + +- `-l, --lines`: Optional. Number of lines to tail (default: 100) + +## Configuration Commands + +### Config + +```bash +unraid-api config +``` + +Displays current configuration values. + +### Switch Environment + +```bash +unraid-api switch-env [-e ] +``` + +Switch between production and staging environments. + +- `-e, --environment`: Optional. Target environment (production|staging) + +### Developer Mode + +```bash +unraid-api developer +``` + +Configure developer features for the API (e.g., GraphQL sandbox). + +## API Key Management + +### API Key Commands + +```bash +unraid-api apikey [options] +``` + +Create and manage API keys. + +Options: + +- `--name `: Name of the key +- `--create`: Create a new key +- `-r, --roles `: Comma-separated list of roles +- `-p, --permissions `: Comma-separated list of permissions +- `-d, --description `: Description for the key + +## SSO (Single Sign-On) Management + +### SSO Base Command + +```bash +unraid-api sso +``` + +#### Add SSO User + +```bash +unraid-api sso add-user +# or +unraid-api sso add +# or +unraid-api sso a +``` + +Add a new user for SSO authentication. + +#### Remove SSO User + +```bash +unraid-api sso remove-user +# or +unraid-api sso remove +# or +unraid-api sso r +``` + +Remove a user (or all users) from SSO. + +#### List SSO Users + +```bash +unraid-api sso list-users +# or +unraid-api sso list +# or +unraid-api sso l +``` + +List all configured SSO users. + +#### Validate SSO Token + +```bash +unraid-api sso validate-token +# or +unraid-api sso validate +# or +unraid-api sso v +``` + +Validates an SSO token and returns its status. + +## Report Generation + +### Generate Report + +```bash +unraid-api report [-r] [-j] +``` + +Generate a system report. + +- `-r, --raw`: Display raw command output +- `-j, --json`: Display output in JSON format + +## Notes + +1. Most commands that modify the system state will require appropriate permissions. +2. Some commands may require the API to be running or stopped depending on their function. +3. When using API keys, ensure you store them securely as they provide access to your system. +4. SSO configuration changes may require a service restart to take effect. diff --git a/docs/API/how-to-use-the-api.md b/docs/API/how-to-use-the-api.md new file mode 100644 index 000000000..a7c93584b --- /dev/null +++ b/docs/API/how-to-use-the-api.md @@ -0,0 +1,202 @@ +# Using the Unraid API + +The Unraid API provides a GraphQL interface that allows you to interact with your Unraid server. This guide will help you get started with exploring and using the API. + +## Enabling the GraphQL Sandbox + +1. First, enable developer mode using the CLI: + +```bash +unraid-api developer +``` + +2. Follow the prompts to enable the sandbox. This will allow you to access the Apollo Sandbox interface. + +3. Access the GraphQL playground by navigating to: + +``` +http://YOUR_SERVER_IP/graphql +``` + +## Authentication + +Most queries and mutations require authentication. You can authenticate using either: + +1. API Keys +2. Cookies (default method when signed into the WebGUI) + +### Creating an API Key + +Use the CLI to create an API key: + +```bash +unraid-api apikey --create +``` + +Follow the prompts to set: + +- Name +- Description +- Roles +- Permissions + +The generated API key should be included in your GraphQL requests as a header: + +```json +{ + "x-api-key": "YOUR_API_KEY" +} +``` + +## Available Schemas + +The API provides access to various aspects of your Unraid server: + +### System Information + +- Query system details including CPU, memory, and OS information +- Monitor system status and health +- Access baseboard and hardware information + +### Array Management + +- Query array status and configuration +- Manage array operations (start/stop) +- Monitor disk status and health +- Perform parity checks + +### Docker Management + +- List and manage Docker containers +- Monitor container status +- Manage Docker networks + +### Remote Access + +- Configure and manage remote access settings +- Handle SSO configuration +- Manage allowed origins + +### Example Queries + +1. Check System Status: + +```graphql +query { + info { + os { + platform + distro + release + uptime + } + cpu { + manufacturer + brand + cores + threads + } + } +} +``` + +2. Monitor Array Status: + +```graphql +query { + array { + state + capacity { + disks { + free + used + total + } + } + disks { + name + size + status + temp + } + } +} +``` + +3. List Docker Containers: + +```graphql +query { + dockerContainers { + id + names + state + status + autoStart + } +} +``` + +## Schema Types + +The API includes several core types: + +### Base Types + +- `Node`: Interface for objects with unique IDs - please see [Object Identification](https://graphql.org/learn/global-object-identification/) +- `JSON`: For complex JSON data +- `DateTime`: For timestamp values +- `Long`: For 64-bit integers + +### Resource Types + +- `Array`: Array and disk management +- `Docker`: Container and network management +- `Info`: System information +- `Config`: Server configuration +- `Connect`: Remote access settings + +### Role-Based Access + +Available roles: + +- `admin`: Full access +- `connect`: Remote access features +- `guest`: Limited read access + +## Best Practices + +1. Use the Apollo Sandbox to explore the schema and test queries +2. Start with small queries and gradually add fields as needed +3. Monitor your query complexity to maintain performance +4. Use appropriate roles and permissions for your API keys +5. Keep your API keys secure and rotate them periodically + +## Rate Limiting + +The API implements rate limiting to prevent abuse. Ensure your applications handle rate limit responses appropriately. + +## Error Handling + +The API returns standard GraphQL errors in the following format: + +```json +{ + "errors": [ + { + "message": "Error description", + "locations": [...], + "path": [...] + } + ] +} +``` + +## Additional Resources + +- Use the Apollo Sandbox's schema explorer to browse all available types and fields +- Check the documentation tab in Apollo Sandbox for detailed field descriptions +- Monitor the API's health using `unraid-api status` +- Generate reports using `unraid-api report` for troubleshooting + +For more information about specific commands and configuration options, refer to the CLI documentation or run `unraid-api --help`. diff --git a/docs/API/index.md b/docs/API/index.md new file mode 100644 index 000000000..b297a7042 --- /dev/null +++ b/docs/API/index.md @@ -0,0 +1,35 @@ +# Unraid API Documentation + +The Unraid API provides a powerful GraphQL interface for interacting with your Unraid server programmatically. It enables automation, monitoring, and integration capabilities for your Unraid system. + +## Current Availability + +The Unraid API is currently available exclusively through the **Unraid Connect Plugin**. To get started: + +1. Install the Unraid Connect Plugin from the Apps tab +2. Configure the plugin according to your needs +3. Access the API functionality through the plugin interface + +## Future Availability + +The API will be integrated directly into the Unraid operating system in an upcoming OS release. This integration will: + +- Make the API a core part of the Unraid system +- Remove the need for separate plugin installation +- Enable deeper system integration capabilities + +## Documentation Sections + +- [How to Use the API](./how-to-use-the-api.md) - Comprehensive guide on using the GraphQL API +- [CLI Commands](./cli.md) - Reference for all available command-line interface commands +- [Upcoming Features](./upcoming-features.md) - Roadmap of planned features and improvements + +## Key Features + +- **GraphQL Interface**: Modern, flexible API design with strong typing +- **Authentication**: Secure access through API keys or session cookies +- **Comprehensive Coverage**: Access to system info, array management, Docker operations, and more +- **Developer Tools**: Built-in GraphQL sandbox for easy exploration and testing +- **Role-Based Access**: Granular control over API permissions and access levels + +For detailed information about using the API, please refer to the [How to Use the API](./how-to-use-the-api.md) guide. diff --git a/docs/API/upcoming-features.md b/docs/API/upcoming-features.md new file mode 100644 index 000000000..2157ebef5 --- /dev/null +++ b/docs/API/upcoming-features.md @@ -0,0 +1,69 @@ +# Unraid API Release Roadmap + +## Core Infrastructure + +| Feature | Status | Tag | +|---------|--------|-----| +| API Development Environment Improvements | Done | v4.0.0 | +| Ship API as part of the OS | Planned (Q1) | - | +| API Open Source | Planned (Q1) | - | +| API / Connect Plugin Split | Planned (Q2) | - | +| Plugin Development Flow (Nest / Nuxt) | Planned (Q2) | - | + +## Security & Authentication + +| Feature | Status | Tag | +|---------|--------|-----| +| Permissions System Rewrite | Done | v4.0.0 | +| UI Library / Component Setup | In Progress | - | + +## User Interface Improvements + +| Feature | Status | Tag | +|---------|--------|-----| +| Generated Settings Page Replacements | Planned (Q2) | - | +| Theme Creator Feature | Planned (Q2-Q3) | - | +| Replace Connect settings page with web component | Planned (Q1) | - | + +## Array Management + +| Feature | Status | Tag | +|---------|--------|-----| +| Array Status API Read Only | Done | v4.0.0 | +| Pool Creation UI / API | Planned (Q2) | - | +| Pool Status UI / API | Planned (Q2) | - | + +## Docker Integration + +| Feature | Status | Tag | +|---------|--------|-----| +| Docker Status API (Read Only) | Done | v4.0.0 | +| Docker Status View Design | Planned (Q3) | - | +| Docker Status View Implementation | Planned (Q3) | - | +| Docker Setup View (Generated UI) | Planned (Q3) | - | +| Docker Compose Support | Planned | - | + +## Share Management + +| Feature | Status | Tag | +|---------|--------|-----| +| Share Status API (Read Only) | Done | v4.0.0 | +| Shares Setup API | Planned | - | +| Shares Setup / Display UI | Planned | - | + +## Plugin System + +| Feature | Status | Tag | +|---------|--------|-----| +| Plugins Tab Migration to API | Planned (Q3) | - | +| Plugin UI | Planned | - | +| Plugin Development Flows | Planned | - | + +## Notifications + +| Feature | Status | Tag | +|---------|--------|-----| +| Notifications API | Done | v4.0.0 | +| Notifications UI | Done | v4.0.0 | + +Note: This roadmap is subject to change based on development priorities and community feedback. Features marked as "Done" have been released in previous versions. The tag column indicates the version where a feature was first introduced. Features without tags are either planned or in development.