User Guide Overview¶

Welcome to the Apiary User Guide! This guide covers everything you need to know to build production-ready APIs with Apiary.

What You'll Learn¶

This guide is organized into the following sections:

Core Concepts¶

Adding Endpoints - Learn how to create API endpoints
- Code-based endpoints (traditional FastAPI)
- Configuration-based endpoints (Apiary's unique feature)
Creating Services - Build reusable business logic
- Service architecture
- Base service interface
Authentication - Secure your API
- API key authentication
- Public vs protected endpoints

Built-in Features¶

Built-in Endpoints - Understand what's included
- Health checks
- Metrics
- Endpoint discovery
- Authentication endpoints
API Key Validation - Validate and manage API keys
- Configuration validation
- Key file management / Hot-reloading keys
Advanced Configuration - Master configuration techniques
- Environment files
- Update-safe deployment
- Per-endpoint configuration

Apiary Architecture¶

Understanding Apiary's architecture will help you make the most of its features.

Core Components¶

┌─────────────────────────────────────────┐
│           FastAPI Application           │
└─────────────────────────────────────────┘
                    │
        ┌───────────┴───────────┐
        │                       │
┌───────▼────────┐    ┌────────▼────────┐
│  Code-based    │    │ Config-based    │
│  Routers       │    │ Endpoints       │
└───────┬────────┘    └────────┬────────┘
        │                      │
        │        ┌─────────────┘
        │        │
┌───────▼────────▼────────┐
│      Services           │
│  (Business Logic)       │
└─────────────────────────┘
        │
┌───────▼────────────────┐
│  External APIs /       │
│  Databases / etc.      │
└────────────────────────┘

Request Flow¶

Request arrives at FastAPI
Middleware processes request (logging, rate limiting, validation)
Router dispatches to appropriate handler
Service executes business logic
Response returned with proper formatting

Key Principles¶

1. Separation of Concerns¶

Routers: Handle HTTP requests/responses
Services: Contain business logic
Models: Define data structures
Middleware: Cross-cutting concerns

2. Dependency Injection¶

Everything uses FastAPI's dependency injection:

@router.get("/endpoint")
async def endpoint(
    client: httpx.AsyncClient = Depends(http_client_dependency),
    settings: Settings = Depends(get_settings),
):
    # Use injected dependencies
    pass

3. Configuration-Driven¶

Much of the behavior can be controlled via configuration:

Endpoints can be added without code
Features can be enabled/disabled
Rate limits are configurable
Services are pluggable

Two Approaches to Endpoints¶

Apiary supports two ways to create endpoints. Choose based on your needs:

Code-Based Endpoints¶

Best for:

Complex logic
Custom validation
Special error handling
Direct control

Example:

@router.get("/complex")
async def complex_endpoint(
    param: str,
    client: httpx.AsyncClient = Depends(http_client_dependency),
):
    # Complex custom logic
    result = await do_something_complex()
    return result

Configuration-Based Endpoints¶

Best for:

Simple service calls
Rapid prototyping
Enabling/disabling features
No code deployments

Example:

{
  "path": "/api/crypto",
  "method": "GET",
  "service": "crypto",
  "enabled": true
}

Common Patterns¶

Public Endpoint¶

Accessible without authentication:

@router.get("/public")
async def public_endpoint():
    return {"message": "Public data"}

Or in configuration:

{
  "path": "/api/public",
  "requires_auth": false
}

Protected Endpoint¶

Requires API key:

@router.get("/protected")
async def protected_endpoint(
    user: AuthenticatedUser = Depends(require_auth)
):
    return {"message": "Protected data"}

Or in configuration:

{
  "path": "/api/protected",
  "requires_auth": true
}

Cached Endpoint¶

Add caching to reduce load:

from core.cache import add_cache_headers

@router.get("/cached")
async def cached_endpoint(response: Response):
    data = expensive_operation()
    add_cache_headers(response, ttl=60)  # Cache 60s
    return data

Aggregation Endpoint¶

Combine multiple services:

@router.get("/combined")
async def combined_endpoint(
    client: httpx.AsyncClient = Depends(http_client_dependency)
):
    crypto = await crypto_service.call()
    weather = await weather_service.call()

    return {
        "crypto": crypto,
        "weather": weather
    }

Where to Go From Here¶

Beginner Path¶

Adding Endpoints - Start here
Creating Services - Build logic
Built-in Endpoints - Use what's included
Quick Start - Hands-on tutorial

Intermediate Path¶

Authentication - Secure your API
Advanced Endpoints - Master advanced patterns
Advanced Configuration - Environment files and security

Advanced Path¶

Advanced Configuration - Master configuration patterns
Core Modules - Deep dive
Deployment - Go to production
Monitoring - Track performance

Ready to dive in? Continue with Adding Endpoints!