Skip to content

Configuration

Jump to bottom
Claude edited this page Oct 14, 2025 · 5 revisions

Configuration

Complete guide to API Dock configuration structure.

Configuration Discovery

API Dock searches for configurations in this order:

  1. Project directory: api_dock_config/config.yaml
  2. Current directory: config/config.yaml
  3. Package defaults: api_dock/config/config.yaml

Main Configuration

The main configuration file defines global settings and lists remotes/databases.

Basic Structure

name: my-api-gateway
description: Production API gateway
authors:
  - name: Your Name
    email: you@example.com

remotes:
  - service1
  - service2
  - api_v2

databases:
  - user_db
  - analytics_db

endpoints:
  - "/"  # API metadata endpoint

# Global route restrictions (applied to all remotes)
restricted:
  - users/{{user_id}}/delete
  - admin/{{admin_id}}/dangerous

Configuration Fields

Field Type Description
name string API gateway name
description string Description shown in API metadata
authors list Author information
remotes list List of remote API names
databases list List of database names
endpoints list Non-proxied endpoints
restricted list Globally restricted route patterns

Remote Configuration

Remote configurations define individual backend APIs.

File Location

config/remotes/
├── service1.yaml
├── service2.yaml
└── versioned_api/
    ├── 0.1.yaml
    ├── 0.2.yaml
    └── 1.0.yaml

Basic Remote

name: service1
description: User management service
url: http://localhost:8001

routes:
  - users
  - users/{{user_id}}
  - users/{{user_id}}/profile

Remote with Custom Mapping

name: service2
description: Legacy API with custom routes
url: http://localhost:8002

routes:
  - route: {{route_name}}/{{user_id}}/permissions
    method: GET
    remote_route: user-permissions/{{user_id}}

  - route: users/{{user_id}}/settings
    method: GET
    remote_route: user-config/{{user_id}}

Remote with Restrictions

name: restricted_api
description: API with additional security
url: http://localhost:8003

restricted:
  - users/{{user_id}}/permissions
  - admin/{{}}

routes:
  - users
  - users/{{user_id}}
  - health

Database Configuration

Database configurations define SQL-queryable data sources.

File Location

config/databases/
├── user_db.yaml
├── analytics_db.yaml
└── versioned_db/
    ├── 0.1.yaml
    └── 1.0.yaml

Basic Database

name: user_db
description: User data warehouse

tables:
  users: s3://my-bucket/users.parquet
  permissions: databases/permissions.parquet

routes:
  - route: users
    sql: SELECT * FROM [[users]]

  - route: users/{{user_id}}
    sql: SELECT * FROM [[users]] WHERE user_id = {{user_id}}

Database with Named Queries

name: analytics_db
description: Analytics database

tables:
  events: s3://analytics/events.parquet
  users: s3://analytics/users.parquet

queries:
  user_events: |
    SELECT e.*
    FROM [[events]] e
    WHERE e.user_id = {{user_id}}

routes:
  - route: users/{{user_id}}/events
    sql: "[[user_events]]"

Directory Structure

Recommended project structure:

my_project/
├── api_dock_config/
│   ├── config.yaml           # Main configuration
│   ├── remotes/              # Remote API configs
│   │   ├── service1.yaml
│   │   ├── service2.yaml
│   │   └── api_v2/           # Versioned remote
│   │       ├── 0.1.yaml
│   │       └── 1.0.yaml
│   └── databases/            # Database configs
│       ├── user_db.yaml
│       └── analytics_db/     # Versioned database
│           ├── 0.1.yaml
│           └── 1.0.yaml
├── databases/                # Local Parquet files (generated from toy_api)
│   ├── test_db/
│   │   ├── users.parquet
│   │   └── permissions.parquet
│   └── versioned_db/
│       └── 1.2/
│           ├── users.parquet
│           ├── posts.parquet
│           └── user_permissions.parquet
└── ...

Initialization

Create configuration directory:

pixi run api-dock init

This creates:

api_dock_config/
├── config.yaml
├── remotes/
└── databases/

Environment-Specific Configs

Use different config directories per environment:

# Development
pixi run api-dock start --config dev_config/config.yaml

# Staging
pixi run api-dock start --config staging_config/config.yaml

# Production
pixi run api-dock start --config prod_config/config.yaml

Best Practices

  1. Version control configs - Commit api_dock_config/ to git
  2. Separate environments - Use different config directories
  3. Document restrictions - Comment why routes are restricted
  4. Use versioning - Version APIs and databases independently
  5. Test configurations - Use describe command to verify

Configuration Validation

Describe configuration to see expanded values:

# View remote configuration
pixi run api-dock describe service1

# View database configuration
pixi run api-dock describe user_db

See Also

Clone this wiki locally