mirror/api
1
0
Fork 0
mirror of https://github.com/unraid/api.git synced 2026-01-05 08:00:33 -06:00
Code Issues Packages Projects Releases Wiki Activity

docs: enhance API documentation with structured sections and tips

Browse Source 
- Added front matter to CLI and API usage documentation for better organization.
- Introduced tips and info boxes to highlight important information and best practices.
- Updated sections with icons for improved visual clarity and navigation.
- Enhanced the OIDC provider setup guide with quick start instructions and detailed configuration tips.
This commit is contained in:
Eli Bosley
2025-08-15 13:22:50 -04:00
parent bcaacca061
commit ce63d5dca2
4 changed files with 143 additions and 40 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
api/docs/public/cli.md
View File

@@ -1,5 +1,17 @@
---
title: CLI Reference
description: Complete reference for all Unraid API CLI commands
sidebar_position: 4
---
# CLI Commands
:::info[Command Structure]
All commands follow the pattern: `unraid-api <command> [options]`
:::
## 🚀 Service Management
### Start
```bash
@@ -39,7 +51,7 @@ View the API logs.
- `-l, --lines`: Optional. Number of lines to tail (default: 100)
## Configuration Commands
## ⚙️ Configuration Commands
### Config

67
api/docs/public/how-to-use-the-api.md
View File

@@ -1,11 +1,25 @@
---
title: Using the Unraid API
description: Learn how to interact with your Unraid server through the GraphQL API
sidebar_position: 2
---
# Using the Unraid API
:::tip[Quick Start]
The Unraid API provides a powerful GraphQL interface for managing your server. This guide covers authentication, common queries, and best practices.
:::
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
## 🎮 Enabling the GraphQL Sandbox
### Web GUI Method (Recommended)
:::info[Preferred Method]
Using the Web GUI is the easiest way to enable the GraphQL sandbox.
:::
1. Navigate to **Settings** → **Management Access** → **Developer Options**
2. Enable the **GraphQL Sandbox** toggle
3. Access the GraphQL playground by navigating to:
@@ -28,17 +42,22 @@ Or use the interactive mode:
unraid-api developer
```
## Authentication
## 🔑 Authentication
Most queries and mutations require authentication. You can authenticate using either:
:::warning[Required for Most Operations]
Most queries and mutations require authentication. Always include appropriate credentials in your requests.
:::
1. API Keys
2. Cookies (default method when signed into the WebGUI)
3. SSO/OIDC (when configured)
You can authenticate using:
1. **API Keys** - For programmatic access
2. **Cookies** - Automatic when signed into the WebGUI
3. **SSO/OIDC** - When configured with external providers
### Managing API Keys
#### Web GUI Method (Recommended)
<tabs>
<tabItem value="gui" label="Web GUI (Recommended)" default>
Navigate to **Settings** → **Management Access** → **API Keys** in your Unraid web interface to:
@@ -47,7 +66,8 @@ Navigate to **Settings** → **Management Access** → **API Keys** in your Unra
- Manage permissions and roles
- Revoke or regenerate keys
#### CLI Method
</tabItem>
<tabItem value="cli" label="CLI Method">
You can also use the CLI to create an API key:
@@ -62,6 +82,9 @@ Follow the prompts to set:
- Roles
- Permissions
</tabItem>
</tabs>
### Using API Keys
The generated API key should be included in your GraphQL requests as a header:
@@ -72,7 +95,7 @@ The generated API key should be included in your GraphQL requests as a header:
}
```
## Available Schemas
## 📊 Available Schemas
The API provides access to various aspects of your Unraid server:
@@ -101,9 +124,9 @@ The API provides access to various aspects of your Unraid server:
- Handle SSO configuration
- Manage allowed origins
### Example Queries
### 💻 Example Queries
1. Check System Status:
#### Check System Status
```graphql
query {
@@ -124,7 +147,7 @@ query {
}
```
2. Monitor Array Status:
#### Monitor Array Status
```graphql
query {
@@ -147,7 +170,7 @@ query {
}
```
3. List Docker Containers:
#### List Docker Containers
```graphql
query {
@@ -161,7 +184,7 @@ query {
}
```
## Schema Types
## 🏗️ Schema Types
The API includes several core types:
@@ -188,19 +211,23 @@ Available roles:
- `connect`: Remote access features
- `guest`: Limited read access
## Best Practices
## ✨ Best Practices
:::tip[Pro Tips]
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
## ⏱️ Rate Limiting
:::caution[Rate Limits]
The API implements rate limiting to prevent abuse. Ensure your applications handle rate limit responses appropriately.
:::
## Error Handling
## 🚨 Error Handling
The API returns standard GraphQL errors in the following format:
@@ -216,11 +243,13 @@ The API returns standard GraphQL errors in the following format:
}
```
## Additional Resources
## 📚 Additional Resources
:::info[Learn More]
- 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`.
For more information about specific commands and configuration options, refer to the [CLI documentation](/cli) or run `unraid-api --help`.
:::

66
api/docs/public/index.md
View File

@@ -1,10 +1,20 @@
# Unraid API
---
title: Welcome to Unraid API
description: The official GraphQL API for Unraid Server management and automation
sidebar_position: 1
---
# Welcome to Unraid API
:::tip[What's New]
Native integration in Unraid v7.2+ brings the API directly into the OS - no plugin needed!
:::
The Unraid API provides a GraphQL interface for programmatic interaction with your Unraid server. It enables automation, monitoring, and integration capabilities.
## Availability
## 📦 Availability
### Native Integration (Unraid v7.2-beta.1+)
### ✨ Native Integration (Unraid v7.2-beta.1+)
Starting with Unraid v7.2-beta.1, the API is integrated directly into the Unraid operating system:
@@ -13,7 +23,7 @@ Starting with Unraid v7.2-beta.1, the API is integrated directly into the Unraid
- Deep system integration
- Access through **Settings** → **Management Access** → **API**
### Plugin Installation (Earlier Versions)
### 🔌 Plugin Installation (Earlier Versions)
For Unraid versions prior to v7.2:
@@ -25,15 +35,27 @@ For Unraid versions prior to v7.2:
You can install the Unraid Connect plugin on any version to access pre-release versions of the API and get early access to new features before they're included in Unraid OS releases.
:::
## Documentation Sections
## 📚 Documentation Sections
- [CLI Commands](./cli.md) - Reference for all available command-line interface commands
- [Using the Unraid API](./how-to-use-the-api.md) - Comprehensive guide on using the GraphQL API
- [OIDC Provider Setup](./oidc-provider-setup.md) - OIDC SSO provider configuration examples
- [Upcoming Features](./upcoming-features.md) - Roadmap of planned features and improvements
<cards>
<card title="CLI Commands" icon="terminal" href="./cli">
Complete reference for all CLI commands
</card>
<card title="Using the API" icon="code" href="./how-to-use-the-api">
Learn how to interact with the GraphQL API
</card>
<card title="OIDC Setup" icon="shield" href="./oidc-provider-setup">
Configure SSO authentication providers
</card>
<card title="Upcoming Features" icon="rocket" href="./upcoming-features">
See what's coming next
</card>
</cards>
## Key Features
## 🌟 Key Features
:::info[Core Capabilities]
The API provides:
- **GraphQL Interface**: Modern, flexible API with strong typing
@@ -42,5 +64,27 @@ The API provides:
- **Developer Tools**: Built-in GraphQL sandbox configurable via web interface or CLI
- **Role-Based Access**: Granular permission control
- **Web Management**: Manage API keys and settings through the web interface
:::
For detailed usage instructions, see [CLI Commands](./cli.md).
## 🚀 Get Started
<tabs>
<tabItem value="v72" label="Unraid v7.2+" default>
1. Access the API settings at **Settings** → **Management Access** → **API**
2. Enable the GraphQL Sandbox for development
3. Create your first API key
4. Start making GraphQL queries!
</tabItem>
<tabItem value="older" label="Earlier Versions">
1. Install the Unraid Connect plugin from Apps
2. Configure the plugin settings
3. Enable the GraphQL Sandbox
4. Start exploring the API!
</tabItem>
</tabs>
For detailed usage instructions, see the [CLI Commands](./cli) reference.

36
api/docs/public/oidc-provider-setup.md
View File

@@ -6,14 +6,23 @@ sidebar_position: 3
# OIDC Provider Setup
:::info[What is OIDC?]
OpenID Connect (OIDC) is an authentication protocol that allows users to sign in using their existing accounts from providers like Google, Microsoft, or your corporate identity provider. It enables Single Sign-On (SSO) for seamless and secure authentication.
:::
This guide walks you through configuring OIDC (OpenID Connect) providers for SSO authentication in the Unraid API using the web interface.
## Accessing OIDC Settings
## 🚀 Quick Start
<details open>
<summary><strong>Getting to OIDC Settings</strong></summary>
1. Navigate to your Unraid server's web interface
2. Go to **Settings** → **Management Access** → **API** → **OIDC**
3. You'll see tabs for different providers - click the **+** button to add a new provider
</details>
### OIDC Providers Interface Overview
![Login Page with SSO Options](./images/sso-with-options.png)
@@ -191,13 +200,17 @@ When "advanced" mode is selected, you'll see:
### Required Redirect URI
All providers must be configured with this redirect URI:
:::caution[Important Configuration]
All providers must be configured with this exact redirect URI format:
:::
```
```bash
http://YOUR_UNRAID_IP/graphql/api/auth/oidc/callback
```
Replace `YOUR_UNRAID_IP` with your actual server IP address.
:::tip
Replace `YOUR_UNRAID_IP` with your actual server IP address (e.g., `192.168.1.100` or `tower.local`).
:::
### Issuer URL Format
@@ -214,7 +227,7 @@ The **Issuer URL** field accepts both formats, but **base URL is strongly recomm
- Keycloak: `https://keycloak.example.com/realms/YOUR_REALM`
- Authelia: `https://auth.yourdomain.com`
## Testing Your Configuration
## ✅ Testing Your Configuration
![Login Page with SSO Buttons](./images/sso-with-options.png)
*Unraid login page displaying both traditional username/password authentication and SSO options with customized provider buttons*
@@ -225,7 +238,7 @@ The **Issuer URL** field accepts both formats, but **base URL is strongly recomm
4. Your configured provider button should appear
5. Click to test the login flow
## Troubleshooting
## 🔧 Troubleshooting
### Common Issues
@@ -270,21 +283,21 @@ LOG_LEVEL=debug unraid-api start --debug
- Authorization rule evaluation
- Token validation errors
## Security Best Practices
## 🔐 Security Best Practices
1. **Use Simple Mode for authorization** - Prevents overly accepting configurations and reduces misconfiguration risks
2. **Be specific with authorization** - Don't use overly broad rules
3. **Rotate secrets regularly** - Update client secrets periodically
4. **Test thoroughly** - Verify only intended users can access
## Need Help?
## 💡 Need Help?
- Check provider's OIDC documentation
- Review Unraid API logs for detailed error messages
- Ensure your provider supports standard OIDC discovery
- Verify network connectivity between Unraid and provider
## Provider-Specific Setup
## 🏢 Provider-Specific Setup
### Unraid.net Provider
@@ -304,6 +317,9 @@ Configure authorization rules using Simple Mode (allowed email domains/addresses
### Google
<details>
<summary><strong>📋 Setup Steps</strong></summary>
Set up OAuth 2.0 credentials in [Google Cloud Console](https://console.cloud.google.com/):
1. Go to **APIs & Services** → **Credentials**
@@ -312,6 +328,8 @@ Set up OAuth 2.0 credentials in [Google Cloud Console](https://console.cloud.goo
4. Add your redirect URI to **Authorized redirect URIs**
5. Configure the OAuth consent screen if prompted
</details>
**Configuration:**
- **Issuer URL**: `https://accounts.google.com`