135 lines
3.4 KiB
Markdown
135 lines
3.4 KiB
Markdown
# yarr-api
|
|
|
|
A Rust client library for the Sonarr API.
|
|
|
|
## Overview
|
|
|
|
`yarr-api` provides a strongly-typed, async Rust client for interacting with Sonarr instances. It handles authentication, request/response serialization, and provides convenient methods for all major Sonarr API endpoints.
|
|
|
|
## Features
|
|
|
|
- **Async/await support** - Built on `tokio` and `reqwest`
|
|
- **Type-safe API** - All API responses are strongly typed with `serde`
|
|
- **Error handling** - Comprehensive error types with detailed error information
|
|
- **Easy to use** - Simple client interface with intuitive method names
|
|
- **Well documented** - Extensive documentation and examples
|
|
|
|
## Installation
|
|
|
|
Add this to your `Cargo.toml`:
|
|
|
|
```toml
|
|
[dependencies]
|
|
yarr-api = "0.1.0"
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
```rust
|
|
use yarr_api::{SonarrClient, Result};
|
|
|
|
#[tokio::main]
|
|
async fn main() -> Result<()> {
|
|
// Create a client
|
|
let client = SonarrClient::new(
|
|
"http://localhost:8989".to_string(),
|
|
"your-api-key".to_string()
|
|
);
|
|
|
|
// Get system status
|
|
let status = client.get_system_status().await?;
|
|
println!("Sonarr version: {}", status.version.unwrap_or_default());
|
|
|
|
// Get all series
|
|
let series = client.get_series().await?;
|
|
println!("Total series: {}", series.len());
|
|
|
|
// Get download queue
|
|
let queue = client.get_queue().await?;
|
|
println!("Items in queue: {}", queue.records.len());
|
|
|
|
Ok(())
|
|
}
|
|
```
|
|
|
|
## API Coverage
|
|
|
|
### System
|
|
- ✅ System status
|
|
- ✅ Health check
|
|
|
|
### Series Management
|
|
- ✅ List all series
|
|
- ✅ Get series by ID
|
|
- ✅ Search for series
|
|
- ✅ Add new series
|
|
|
|
### Episodes
|
|
- ✅ Get episodes for series/season
|
|
- ✅ Get calendar (upcoming episodes)
|
|
- ✅ Get missing episodes
|
|
|
|
### Downloads
|
|
- ✅ Get download queue
|
|
- ✅ Get download history
|
|
|
|
## Examples
|
|
|
|
See the `examples/` directory for more comprehensive usage examples:
|
|
|
|
```bash
|
|
# Run the basic usage example
|
|
cargo run --example basic_usage
|
|
|
|
# Make sure to set your Sonarr URL and API key first:
|
|
export SONARR_URL="http://localhost:8989"
|
|
export SONARR_API_KEY="your-api-key-here"
|
|
```
|
|
|
|
## Error Handling
|
|
|
|
The library uses a custom `ApiError` type that provides detailed error information:
|
|
|
|
```rust
|
|
use yarr_api::{SonarrClient, ApiError};
|
|
|
|
let client = SonarrClient::new(url, api_key);
|
|
|
|
match client.get_series().await {
|
|
Ok(series) => println!("Found {} series", series.len()),
|
|
Err(ApiError::Authentication) => println!("Invalid API key"),
|
|
Err(ApiError::NotFound) => println!("Endpoint not found"),
|
|
Err(ApiError::ServerError) => println!("Sonarr server error"),
|
|
Err(e) => println!("Other error: {}", e),
|
|
}
|
|
```
|
|
|
|
## Configuration
|
|
|
|
The client requires two pieces of information:
|
|
|
|
1. **Base URL** - The URL of your Sonarr instance (e.g., `http://localhost:8989`)
|
|
2. **API Key** - Your Sonarr API key (found in Settings > General > Security)
|
|
|
|
## Data Types
|
|
|
|
All Sonarr API responses are represented as strongly-typed Rust structs:
|
|
|
|
- `SystemStatus` - System information and status
|
|
- `Series` - TV series information
|
|
- `Episode` - Episode details
|
|
- `QueueItem` - Download queue items
|
|
- `HistoryItem` - Download history
|
|
- `HealthResource` - Health check results
|
|
|
|
## Contributing
|
|
|
|
Contributions are welcome! Please feel free to submit a Pull Request.
|
|
|
|
## License
|
|
|
|
This project is licensed under the MIT License - see the LICENSE file for details.
|
|
|
|
## Related Projects
|
|
|
|
- [yarr](../yarr-cli) - TUI client for Sonarr built using this library |