mirror of
https://github.com/unraid/api.git
synced 2025-12-31 13:39:52 -06:00
feat: auto-docusaurus-prs (#1127)
<!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit - **Documentation** - Expanded the Unraid API guides with comprehensive CLI command details for managing services, logs, configuration, and authentication. - Updated the API usage instructions to include steps for enabling a GraphQL sandbox, example queries, error handling, and best practices. - Added an implementation overview detailing component capabilities and a release roadmap outlining upcoming improvements across core infrastructure, security, and user interface. - **Chores** - Introduced automation that streamlines the updating of API documentation. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
This commit is contained in:
Eli Bosley
55
.github/workflows/create-docusaurus-pr.yml
vendored
Normal file
55
.github/workflows/create-docusaurus-pr.yml
vendored
Normal file
@@ -0,0 +1,55 @@
|
||||
name: Update API Documentation
|
||||
|
||||
name: Update API Documentation
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- main
|
||||
paths:
|
||||
- 'api/docs/**'
|
||||
concurrency:
|
||||
group: ${{ github.workflow }}-${{ github.ref }}
|
||||
cancel-in-progress: true
|
||||
|
||||
# Add permissions for GITHUB_TOKEN
|
||||
permissions:
|
||||
contents: write
|
||||
pull-requests: write
|
||||
jobs:
|
||||
create-docs-pr:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Checkout source repository
|
||||
uses: actions/checkout@v4
|
||||
with:
|
||||
path: source-repo
|
||||
|
||||
- name: Checkout docs repository
|
||||
uses: actions/checkout@v4
|
||||
with:
|
||||
repository: unraid/docs
|
||||
path: docs-repo
|
||||
token: ${{ github.token }}
|
||||
|
||||
- name: Copy updated docs
|
||||
run: |
|
||||
if [ ! -d "source-repo/api/docs" ]; then
|
||||
echo "Source directory does not exist!"
|
||||
exit 1
|
||||
fi
|
||||
mkdir -p docs-repo/docs/api
|
||||
cp -r source-repo/api/docs/* docs-repo/docs/api/
|
||||
- name: Create Pull Request
|
||||
uses: peter-evans/create-pull-request@v6
|
||||
with:
|
||||
token: ${{ github.token }}
|
||||
path: docs-repo
|
||||
commit-message: 'docs: update API documentation'
|
||||
title: 'Update API Documentation'
|
||||
body: |
|
||||
This PR updates the API documentation based on changes from the main repository.
|
||||
|
||||
Changes were automatically generated from api/docs/* directory.
|
||||
branch: update-api-docs
|
||||
base: main
|
||||
delete-branch: true
|
||||
161
api/docs/cli.md
Normal file
161
api/docs/cli.md
Normal file
@@ -0,0 +1,161 @@
|
||||
# CLI Commands
|
||||
|
||||
### Start
|
||||
|
||||
```bash
|
||||
unraid-api start [--log-level <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 <lines>]
|
||||
```
|
||||
|
||||
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 <environment>]
|
||||
```
|
||||
|
||||
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>`: Name of the key
|
||||
- `--create`: Create a new key
|
||||
- `-r, --roles <roles>`: Comma-separated list of roles
|
||||
- `-p, --permissions <permissions>`: Comma-separated list of permissions
|
||||
- `-d, --description <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 <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.
|
||||
136
api/docs/feature-implementation.md
Normal file
136
api/docs/feature-implementation.md
Normal file
@@ -0,0 +1,136 @@
|
||||
# Unraid API Project Status
|
||||
|
||||
This document outlines the current implementation status of various Unraid components in the API.
|
||||
|
||||
## Implementation Status Legend
|
||||
|
||||
- ✅ Fully Implemented
|
||||
- 🟡 Partially Implemented
|
||||
- ❌ Not Implemented
|
||||
- 🔒 Requires Authentication
|
||||
|
||||
## Core Components
|
||||
|
||||
| Component | Read | Write | Update | Notes |
|
||||
|-----------|------|-------|--------|-------|
|
||||
| Array | ✅ 🔒 | ✅ 🔒 | ✅ 🔒 | Full array management including start/stop/status |
|
||||
| Parity | ✅ 🔒 | ✅ 🔒 | ✅ 🔒 | Check/pause/resume functionality |
|
||||
| Disks | ✅ 🔒 | ✅ 🔒 | ✅ 🔒 | Comprehensive disk management |
|
||||
| Docker | ✅ 🔒 | ✅ 🔒 | ✅ 🔒 | Container and network management |
|
||||
|
||||
## System Information
|
||||
|
||||
| Component | Read | Write | Notes |
|
||||
|-----------|------|-------|-------|
|
||||
| CPU | ✅ | ❌ | Detailed CPU information including cores, cache, flags |
|
||||
| Memory | ✅ | ❌ | RAM and swap information |
|
||||
| OS | ✅ | ❌ | System version and kernel details |
|
||||
| Hardware | ✅ | ❌ | Baseboard and system information |
|
||||
| Network | ✅ | 🟡 | Basic network interface information |
|
||||
|
||||
## Configuration & Management
|
||||
|
||||
| Component | Read | Write | Update | Notes |
|
||||
|-----------|------|-------|--------|-------|
|
||||
| API Keys | ✅ 🔒 | ✅ 🔒 | ✅ 🔒 | Full CRUD operations |
|
||||
| SSO | ✅ 🔒 | ✅ 🔒 | ✅ 🔒 | Complete SSO integration |
|
||||
| Remote Access | ✅ 🔒 | ✅ 🔒 | ✅ 🔒 | Dynamic and static access configuration |
|
||||
| Display Settings | ✅ 🔒 | 🟡 | 🟡 | Basic display configuration |
|
||||
|
||||
## Device Management
|
||||
|
||||
| Component | Read | Write | Notes |
|
||||
|-----------|------|-------|-------|
|
||||
| GPU | ✅ | ❌ | Basic GPU information |
|
||||
| USB Devices | ✅ | ❌ | Basic USB device enumeration |
|
||||
| PCI Devices | ✅ | ❌ | PCI device information |
|
||||
| Storage Devices | ✅ | 🟡 | Comprehensive storage information |
|
||||
|
||||
## Security & Authentication
|
||||
|
||||
| Feature | Status | Notes |
|
||||
|---------|--------|-------|
|
||||
| Role-Based Access | ✅ | Implemented roles: admin, connect, guest |
|
||||
| API Key Authentication | ✅ | Full implementation with key management |
|
||||
| Permission System | ✅ | Granular resource-based permissions |
|
||||
| Rate Limiting | ✅ | Implemented with configurable limits |
|
||||
|
||||
## Available Resources
|
||||
|
||||
The following resources are available for API access:
|
||||
|
||||
```typescript
|
||||
enum Resource {
|
||||
api_key
|
||||
array
|
||||
cloud
|
||||
config
|
||||
connect
|
||||
connect__remote_access
|
||||
customizations
|
||||
dashboard
|
||||
disk
|
||||
display
|
||||
docker
|
||||
flash
|
||||
info
|
||||
logs
|
||||
me
|
||||
network
|
||||
notifications
|
||||
online
|
||||
os
|
||||
owner
|
||||
permission
|
||||
registration
|
||||
servers
|
||||
services
|
||||
share
|
||||
vars
|
||||
vms
|
||||
welcome
|
||||
}
|
||||
```
|
||||
|
||||
## Authentication Methods
|
||||
|
||||
1. API Key Authentication
|
||||
- Header-based authentication
|
||||
- Role-based access control
|
||||
- Granular permissions
|
||||
|
||||
2. Session-based Authentication
|
||||
- Cookie-based authentication
|
||||
- CSRF protection
|
||||
- Integration with Unraid's existing auth system
|
||||
|
||||
## Rate Limiting
|
||||
|
||||
Current implementation:
|
||||
- 100 requests per 10 seconds per IP
|
||||
- Configurable through ThrottlerModule
|
||||
|
||||
## Development Features
|
||||
|
||||
| Feature | Status | Notes |
|
||||
|---------|--------|-------|
|
||||
| GraphQL Sandbox | ✅ | Available in developer mode |
|
||||
| CLI Tools | ✅ | Comprehensive command line interface |
|
||||
| Error Handling | ✅ | Standardized error responses |
|
||||
| Logging | ✅ | Configurable log levels |
|
||||
|
||||
## Notes
|
||||
|
||||
1. All authenticated endpoints require either:
|
||||
- Valid API key in X-API-Key header
|
||||
- Valid session cookie with CSRF token
|
||||
|
||||
2. Resource access is controlled by:
|
||||
- User roles
|
||||
- Individual permissions
|
||||
- Resource-specific policies
|
||||
|
||||
3. The API implements standard GraphQL features:
|
||||
- Queries for reading data
|
||||
- Mutations for writing/updating data
|
||||
- Subscriptions for real-time updates
|
||||
202
api/docs/how-to-use-the-api.md
Normal file
202
api/docs/how-to-use-the-api.md
Normal file
@@ -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`.
|
||||
69
api/docs/upcoming-features.md
Normal file
69
api/docs/upcoming-features.md
Normal file
@@ -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.
|
||||
Reference in New Issue
Block a user