Configuration¶

Learn how to configure Apiary for your needs.

Configuration Files¶

Apiary uses two main configuration files:

config/settings.json - Application settings (API keys, rate limits, etc.)
config/endpoints.json - Endpoint definitions

Both files are ignored by git (via .gitignore) to keep sensitive data secure and prevent merge conflicts during updates.

Application Settings (`config/settings.json`)¶

Creating Settings File¶

Use the CLI to initialize configuration files:

uv run apiary init

Or manually copy the template:

cp config/settings_template.json config/settings.json

Settings Structure¶

{
  "api_keys": "your-api-key-1,your-api-key-2",
  "enable_landing_page": true,
  "enable_docs": true,
  "enable_redoc": true,
  "enable_openapi": true,
  "enabled_routers": ["health", "metrics", "auth", "endpoints"],
  "rate_limit_enabled": true,
  "rate_limit_per_minute": 60,
  "rate_limit_per_minute_authenticated": 300
}

Configuration Options¶

`api_keys`¶

Comma-separated list of valid API keys for authentication, or a path to a file containing keys.

{
  "api_keys": "secret-key-1,secret-key-2,secret-key-3"
}

Or use a file:

{
  "api_keys": "config/api_keys.txt"
}

Type: String (comma-separated keys or file path)
Default: Empty string (no authentication)
Example: "key1,key2,key3" or "config/api_keys.txt"

Using Key Files

Key files should contain one key per line. Comments starting with # are ignored. Files are automatically monitored and reloaded when changed.

# config/api_keys.txt
key1
key2
key3

Generating API Keys

Generate strong random API keys:

python -c "import secrets; print(secrets.token_urlsafe(32))"

`enable_landing_page`¶

Enable or disable the HTML landing page at /.

{
  "enable_landing_page": true
}

Type: Boolean
Default: true
Values: true (enabled), false (disabled)

`enable_docs`¶

Enable or disable the interactive Swagger UI documentation at /docs.

{
  "enable_docs": true
}

Type: Boolean
Default: true
Values: true (enabled), false (disabled)

API Documentation

The Swagger UI provides an interactive interface to explore and test your API endpoints. Disable this in production if you don't want to expose API documentation publicly.

`enable_redoc`¶

Enable or disable the ReDoc documentation interface at /redoc.

{
  "enable_redoc": true
}

Type: Boolean
Default: true
Values: true (enabled), false (disabled)

Alternative Documentation

ReDoc provides a clean, responsive alternative to Swagger UI for viewing API documentation. It's read-only and optimized for documentation browsing.

`enable_openapi`¶

Enable or disable the OpenAPI schema endpoint at /openapi.json.

{
  "enable_openapi": true
}

Type: Boolean
Default: true
Values: true (enabled), false (disabled)

OpenAPI Schema

The OpenAPI schema can be used by API clients, code generators, and testing tools. Disable this if you want to keep your API schema private.

`enabled_routers`¶

List of routers to enable. This allows you to selectively enable or disable API features without modifying code.

{
  "enabled_routers": ["health", "metrics", "auth", "endpoints"]
}

Type: Array of strings
Default: ["health", "metrics", "auth", "endpoints"]
Built-in routers:
- health - Health check endpoints
- metrics - Application metrics endpoints
- auth - Authentication endpoints (login, token validation)
- endpoints - List available endpoints

Disable Authentication

To run without authentication endpoints:

{
  "enabled_routers": ["health", "metrics", "endpoints"]
}

Custom Routers

Routers are automatically discovered from the routers/ directory. Simply create a router file (e.g., routers/example.py) and add its name to enabled_routers. See Adding Endpoints for details.

`rate_limit_enabled`¶

Enable or disable rate limiting globally.

{
  "rate_limit_enabled": true
}

Type: Boolean
Default: true
Values: true (enabled), false (disabled)

`rate_limit_per_minute`¶

Rate limit for unauthenticated requests (requests per minute per IP).

{
  "rate_limit_per_minute": 60
}

Type: Integer
Default: 60
Example: 60 (60 requests per minute)

`rate_limit_per_minute_authenticated`¶

Rate limit for authenticated requests (requests per minute per API key).

{
  "rate_limit_per_minute_authenticated": 300
}

Type: Integer
Default: 300
Example: 300 (300 requests per minute)

Environment Variables¶

Settings can be overridden with environment variables:

export API_KEYS="key1,key2"
export RATE_LIMIT_ENABLED=true
export RATE_LIMIT_PER_MINUTE=100
export RATE_LIMIT_PER_MINUTE_AUTHENTICATED=500

uv run apiary serve --reload

Environment variables take precedence over config/settings.json.

Example Configurations¶

Development¶

{
  "api_keys": "dev-key-123",
  "enable_landing_page": true,
  "rate_limit_enabled": false
}

Production¶

{
  "api_keys": "prod-key-a1b2c3d4,prod-key-e5f6g7h8",
  "enable_landing_page": true,
  "rate_limit_enabled": true,
  "rate_limit_per_minute": 60,
  "rate_limit_per_minute_authenticated": 300
}

Testing¶

{
  "api_keys": "test-key",
  "enable_landing_page": false,
  "rate_limit_enabled": false
}

Endpoint Configuration (`config/endpoints.json`)¶

Creating Endpoints File¶

Copy the template:

cp config/endpoints_template.json config/endpoints.json

Endpoint Structure¶

{
  "endpoints": [
    {
      "path": "/api/example",
      "method": "GET",
      "service": "example",
      "enabled": true,
      "requires_auth": false,
      "description": "Example endpoint",
      "tags": [
        "example"
      ],
      "summary": "Example endpoint",
      "parameters": {
        "param1": {
          "source": "query",
          "key": "param1"
        }
      }
    }
  ]
}

Endpoint Options¶

`path`¶

The URL path for the endpoint.

Type: String
Required: Yes
Example: "/api/crypto", "/api/hello"
Must start with: /

`method`¶

HTTP method for the endpoint.

Type: String
Required: Yes
Values: "GET", "POST", "PUT", "DELETE", "PATCH"
Example: "GET"

`service`¶

Name of the service to call (must be registered).

Type: String
Required: Yes
Example: "crypto", "hello"

`enabled`¶

Enable or disable the endpoint.

Type: Boolean
Required: Yes
Values: true (enabled), false (disabled)
Example: true

`requires_auth`¶

Whether authentication is required.

Type: Boolean
Required: Yes
Values: true (protected), false (public)
Example: false

`description`¶

Detailed description for API documentation.

Type: String
Required: No
Example: "Get cryptocurrency price data. Accepts optional 'symbol' parameter."

`tags`¶

OpenAPI tags for grouping endpoints.

Type: Array of strings
Required: No
Example: ["crypto", "finance"]

`summary`¶

Short summary for API documentation.

Type: String
Required: No
Example: "Cryptocurrency prices"

`parameters`¶

Parameter mapping from request to service.

Type: Object
Required: No

Parameter mapping types:

{
  "parameters": {
    "static_value": "hardcoded-value",
    "from_query": {
      "source": "query",
      "key": "q"
    },
    "from_path": {
      "source": "path",
      "key": "id"
    }
  }
}

Example Configurations¶

Simple Public Endpoint¶

{
  "path": "/api/crypto",
  "method": "GET",
  "service": "crypto",
  "enabled": true,
  "requires_auth": false,
  "description": "Get cryptocurrency prices",
  "tags": ["crypto"]
}

Protected Endpoint¶

{
  "path": "/api/admin/stats",
  "method": "GET",
  "service": "stats",
  "enabled": true,
  "requires_auth": true,
  "description": "Admin statistics (requires API key)",
  "tags": ["admin"]
}

Endpoint with Parameters¶

{
    "path": "/api/crypto",
    "method": "GET",
    "service": "crypto",
    "enabled": true,
    "requires_auth": false,
    "description": "Get crypto price by symbol",
    "tags": [
        "crypto"
    ],
    "parameters": {
        "symbol": {
            "source": "query",
            "key": "symbol"
        }
    }
}

Disabled Endpoint¶

{
  "path": "/api/beta-feature",
  "method": "GET",
  "service": "beta",
  "enabled": false,
  "requires_auth": false,
  "description": "Beta feature (currently disabled)"
}

Loading Configuration¶

Priority Order¶

Configuration is loaded in this order (higher numbers override lower):

Default values in code
config/settings.json file
Environment variables

Configuration Validation¶

Apiary validates configuration on startup:

Valid JSON syntax
Required fields present
Service names are registered
Endpoint paths start with /
HTTP methods are valid

If validation fails, the application will not start and will show an error message.

Reloading Configuration¶

Configuration is loaded once at startup. To apply changes, restart the server:

## Press Ctrl+C to stop, then

uv run apiary serve --reload

Advanced Topics¶

For advanced configuration including environment files, update-safe deployment patterns, security best practices, and per-endpoint configuration, see:

Advanced Configuration - Environment files, configuration inheritance, security
Configuration Options Reference - Complete configuration reference

Next Steps¶

Adding Endpoints - Learn to create endpoints
Authentication - Implement auth patterns
Deployment Configuration - Production settings

Configuration¶

Configuration Files¶

Application Settings (config/settings.json)¶

Creating Settings File¶

Settings Structure¶

Configuration Options¶

api_keys¶

enable_landing_page¶

enable_docs¶

enable_redoc¶

enable_openapi¶

enabled_routers¶

rate_limit_enabled¶

rate_limit_per_minute¶

rate_limit_per_minute_authenticated¶

Environment Variables¶

Example Configurations¶

Development¶

Production¶

Testing¶

Endpoint Configuration (config/endpoints.json)¶

Creating Endpoints File¶

Endpoint Structure¶

Endpoint Options¶

path¶

method¶

service¶

enabled¶

requires_auth¶

description¶

tags¶

summary¶

parameters¶

Example Configurations¶

Simple Public Endpoint¶

Protected Endpoint¶

Endpoint with Parameters¶

Disabled Endpoint¶

Loading Configuration¶

Priority Order¶

Configuration Validation¶

Reloading Configuration¶

Advanced Topics¶

Next Steps¶

Application Settings (`config/settings.json`)¶

`api_keys`¶

`enable_landing_page`¶

`enable_docs`¶

`enable_redoc`¶

`enable_openapi`¶

`enabled_routers`¶

`rate_limit_enabled`¶

`rate_limit_per_minute`¶

`rate_limit_per_minute_authenticated`¶

Endpoint Configuration (`config/endpoints.json`)¶

`path`¶

`method`¶

`service`¶

`enabled`¶

`requires_auth`¶

`description`¶

`tags`¶

`summary`¶

`parameters`¶