mirror of
https://github.com/unraid/api.git
synced 2025-12-31 13:39:52 -06:00
feat: add developer docs (#1128)
<!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit - **Documentation** - Improved the API documentation update process to enhance clarity and maintain consistent content. - Introduced a comprehensive guide outlining the API's repository organization and system architecture. - Streamlined the documentation by removing outdated developer guides on API introspection and feature implementation. <!-- end of auto-generated comment: release notes by coderabbit.ai -->
This commit is contained in:
Eli Bosley
3
.github/workflows/create-docusaurus-pr.yml
vendored
3
.github/workflows/create-docusaurus-pr.yml
vendored
@@ -35,8 +35,9 @@ jobs:
|
||||
echo "Source directory does not exist!"
|
||||
exit 1
|
||||
fi
|
||||
rm -rf docs-repo/docs/api/
|
||||
mkdir -p docs-repo/docs/api
|
||||
cp -r source-repo/api/docs/* docs-repo/docs/api/
|
||||
cp -r source-repo/api/docs/public* docs-repo/docs/api/
|
||||
- name: Create Pull Request
|
||||
uses: peter-evans/create-pull-request@v6
|
||||
with:
|
||||
|
||||
82
api/docs/developer/repo-organization.md
Normal file
82
api/docs/developer/repo-organization.md
Normal file
@@ -0,0 +1,82 @@
|
||||
# Repository Organization
|
||||
|
||||
This document describes the high-level architecture of the Unraid API repository.
|
||||
|
||||
## Overview
|
||||
|
||||
The repository consists of:
|
||||
|
||||
- API Server (NestJS)
|
||||
- Redux Store
|
||||
- Core Modules
|
||||
- Tests
|
||||
|
||||
## API Server Architecture
|
||||
|
||||
The API server is built with NestJS and provides the core functionality for interacting with Unraid systems.
|
||||
|
||||
### Key Components:
|
||||
|
||||
- `src/unraid-api/` - Core NestJS implementation
|
||||
- `src/core/` - Legacy business logic and utilities
|
||||
- `src/store/` - Redux store and state management
|
||||
- `src/common/` - Shared utilities and types
|
||||
|
||||
## Redux Store
|
||||
|
||||
The store manages application state through several modules:
|
||||
|
||||
### Store Modules
|
||||
|
||||
- `config` - User settings, authentication, and API configuration
|
||||
- `emhttp` - Unraid system and array state
|
||||
- `registration` - License management
|
||||
- `cache` - Application caching
|
||||
- `docker` - Container management
|
||||
- `upnp` - UPnP functionality
|
||||
- `dynamix` - Plugin state
|
||||
- `minigraph` - Mothership connectivity
|
||||
- `notifications` - System notifications
|
||||
|
||||
### Store Listeners
|
||||
|
||||
Key listeners that handle side effects:
|
||||
|
||||
- Array state changes
|
||||
- Configuration updates
|
||||
- Remote access changes
|
||||
- Server state updates
|
||||
- UPnP changes
|
||||
- WAN access changes
|
||||
|
||||
### Store Synchronization
|
||||
|
||||
The store syncs data in two ways:
|
||||
|
||||
- Flash Storage - Persistent configuration
|
||||
- Memory Storage - Runtime state
|
||||
|
||||
## Project Structure
|
||||
|
||||
The repository is organized into several packages:
|
||||
|
||||
- `api/` - NestJS API server
|
||||
- `plugin/` - Unraid plugin package
|
||||
- `web/` - Frontend application
|
||||
- `unraid-ui/` - Shared UI components
|
||||
|
||||
## Development Flow
|
||||
|
||||
New development should focus on the NestJS implementation in `src/unraid-api/`:
|
||||
|
||||
1. Create new features in `src/unraid-api/` using NestJS patterns
|
||||
2. Use dependency injection and NestJS modules
|
||||
3. Legacy code in `src/core/` should be gradually migrated
|
||||
4. State management still uses Redux store when needed
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. Follow NestJS architectural patterns
|
||||
2. Use TypeScript decorators and strong typing
|
||||
3. Implement proper dependency injection
|
||||
4. Write unit tests for new services
|
||||
@@ -1,34 +0,0 @@
|
||||
# How to enable introspection and view possible API endpoints for the Unraid API
|
||||
|
||||
1. Install the API on your machine
|
||||
2. Stop the running api with `unraid-api stop`
|
||||
3. Enable an allowed origin for Apollo Studio:
|
||||
|
||||
- Edit the file at `/boot/config/plugins/dynamix.my.servers/myservers.cfg
|
||||
- Add the line `extraOrigins="studio.apollographql.com"` inside of the `[api]` block
|
||||
|
||||
```ini
|
||||
[api]
|
||||
...
|
||||
extraOrigins="studio.apollographql.com"
|
||||
[local]
|
||||
...rest
|
||||
```
|
||||
|
||||
- Also copy out the `[upc] -> apikey` setting, it should look something like `unupc_52e45431703b1e79cef709bfaf7ddc469bafc12e091b7c9bca0f6e96dc`
|
||||
|
||||
4. Enable introspection
|
||||
|
||||
```sh
|
||||
INTROSPECTION=true LOG_LEVEL=trace LOG_TYPE=pretty unraid-api start --debug
|
||||
```
|
||||
|
||||
- If you run this command and it says the Unraid API is already started, run `unraid-api stop` before trying it again.
|
||||
|
||||
5. Use introspection to your server with Apollo Sandbox:
|
||||
- Navigate your *Chrome* browser to [Apollo Sandbox](https://studio.apollographql.com/sandbox/explorer/)
|
||||
- Click the settings icon in the top right corner and set the URL to your servers URL + /graphql. For example a server URL might be: `https://192-168-1-3.277ace5dd0892eacd83f517b39fb3d1dd32078b5.myunraid.net:8443/graphql` or `http://tower.local/graphql`
|
||||
- Also set the API key you copied earlier in the header section. Set the key as `x-api-key` and the value to the API key you copied in Step 2.
|
||||
|
||||
|
||||
6. Now that your server should be connected, you should see the schema populate. To perform queries, click the plus icon on the field on the left side to add them to a query and then click to run icon on the right.
|
||||
@@ -1,136 +0,0 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user