Skip to content

🐝 Apiary

A Modular, Extensible FastAPI Framework

Apiary is a production-ready FastAPI framework designed for building modular, extensible REST APIs with minimal code. It provides a robust foundation with authentication, rate limiting, metrics, health checks, and a unique configuration-driven endpoint system.

Key Features

Production-Ready

  • Structured logging
  • Rate limiting with configurable limits
  • Health checks (liveness and readiness probes)
  • Metrics collection for monitoring
  • Request validation and size limits
  • Caching support with cache headers

Security

  • API key authentication with flexible authorization
  • Security headers middleware
  • CORS support for cross-origin requests
  • Input sanitization and validation

Modular & Extensible

  • Configuration-driven endpoints - add endpoints without code changes
  • Service-based architecture with dependency injection
  • Plugin system for custom services
  • Endpoint discovery API

Developer Experience

  • Type-safe configuration using Pydantic Settings
  • Comprehensive error handling with standardized responses
  • Auto-generated API documentation (Swagger UI & ReDoc)
  • Testing utilities with mocks and fixtures

Quick Start

# Clone the repository
git clone https://github.com/lancereinsmith/apiary.git
cd apiary

# Install dependencies
uv sync

# Create configuration
uv run apiary init

# Run the application
uv run apiary serve --reload

# Visit `http://localhost:8000/docs` for interactive API documentation.

What Makes Apiary Different?

Configuration-Driven Endpoints

Add new API endpoints without writing code - just edit a JSON configuration file:

{
  "endpoints": [
    {
      "path": "/api/crypto",
      "method": "GET",
      "service": "crypto",
      "enabled": true,
      "requires_auth": false,
      "description": "Get cryptocurrency price data. Accepts optional 'symbol' parameter (e.g., BTC, ETH, SOL). Defaults to BTC if not provided.",
      "tags": ["crypto"],
      "summary": "Cryptocurrency price data"
    }
  ]
}

Service-Based Architecture

Create reusable services that can be called by multiple endpoints:

from core.services.base import BaseService

class MyService(BaseService):
    service_name = "my_service"
    async def call(self, parameters=None):
        # Your business logic here
        return {"result": "data"}

Register the service and use it in configurable endpoints or code-based routes.

Use Cases

Apiary is perfect for:

  • Personal APIs: Quickly build APIs for personal projects
  • Microservices: Create modular, maintainable microservices
  • API Gateways: Build custom API gateways with routing and aggregation
  • Rapid Prototyping: Test ideas with configuration-driven endpoints

Architecture Overview

apiary/
├── config/              # Configuration management
│   ├── settings.py      # Pydantic Settings
│   └── endpoint_config.py  # Endpoint loader
├── core/                # Core utilities
│   ├── auth/            # Authentication & authorization
│   ├── services/        # Base service classes
│   ├── exceptions.py    # Custom exceptions
│   ├── middleware.py    # Custom middleware
│   ├── rate_limiter.py  # Rate limiting
│   ├── metrics.py       # Metrics collection
│   └── cache.py         # Caching utilities
├── routers/             # API route handlers
├── services/            # Business logic services
├── models/              # Request/response models
├── templates/           # HTML templates
├── app.py               # FastAPI application factory
└── cli.py               # CLI commands

Built-in Endpoints

  • GET / - Landing page
  • GET /health - Health check
  • GET /health/live - Liveness probe
  • GET /health/ready - Readiness probe
  • GET /metrics - Application metrics
  • GET /endpoints - Endpoint discovery
  • GET /auth/status - Authentication status
  • GET /auth/validate - Validate API key

Next Steps

  1. Installation Guide - Set up your environment
  2. Quick Start - Build your first API
  3. Configuration - Configure your application
  4. Adding Endpoints - Learn to add endpoints
  5. Creating Services - Build custom services

Community & Support

License

This project is open source and available under the MIT License.