Skip to content

Home

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

API Dock Wiki

Complete documentation for API Dock - a powerful API gateway with routing, restrictions, and SQL database support.

Quick Links

Documentation

Core Guides

Guide Description
Configuration Main and remote configuration structure
Routing and Restrictions Route patterns, restrictions, and custom mappings
SQL Database Support Query databases with DuckDB through REST endpoints
Versioning Version remotes and databases independently

Topics

Routing

  • Routing and Restrictions - Complete routing guide
    • Bracket notation: {{}} for URL vars, [[]] for config references
    • Route patterns and variable placeholders
    • Global and remote-specific restrictions
    • Whitelist vs blacklist approaches
    • Custom route mapping

Databases

  • SQL Database Support - Query data through APIs
    • DuckDB integration for Parquet files
    • Cloud storage support (S3, GCS, HTTPS)
    • SQL syntax with table and parameter references
    • Named queries for reuse
    • Complex JOINs and aggregations

Configuration

  • Configuration - Configuration structure and best practices
    • Main configuration file
    • Remote API configurations
    • Database configurations
    • Directory structure
    • Environment-specific configs

Versioning

  • Versioning - Version management
    • Subdirectory-based versioning
    • Smart version sorting (float-first, string fallback)
    • /latest/ endpoint for highest version
    • Version metadata endpoints
    • Migration strategies

Installation

Using pixi (recommended):

pixi add api-dock

Using pip:

pip install api-dock

Quick Start

# Initialize configuration
api-dock init

# Start API Dock
api-dock start

# View configuration
api-dock describe my_remote

Common Tasks

Configure a Remote API

# Create remote config
cat > api_dock_config/remotes/my_api.yaml <<EOF
name: my_api
url: http://localhost:3000
routes:
  - users
  - users/{{user_id}}
  - posts
EOF

# Start API Dock
api-dock start

Setup SQL Database

# Create database config
cat > api_dock_config/databases/users.yaml <<EOF
name: users
tables:
  users: s3://my-bucket/users.parquet

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

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

# Query database
curl http://localhost:8000/users/users
curl http://localhost:8000/users/users/123

Add Route Restrictions

# config.yaml - Global restrictions
restricted:
  - users/{{user_id}}/delete
  - admin/{{}}

# remotes/secure_api.yaml - Whitelist approach
routes:
  - users
  - users/{{user_id}}
  - health

Architecture

API Dock acts as a unified gateway:

Client Request
     ↓
API Dock (port 8000)
     ├→ Remote APIs (HTTP proxy)
     ├→ Databases (SQL queries)
     └→ Version routing

Use Cases

  • API Aggregation - Single endpoint for multiple backend services
  • Security Layer - Route restrictions and access control
  • Legacy API Modernization - Custom route mapping for old APIs
  • Data APIs - Query Parquet files through REST endpoints
  • Testing - Mock APIs with configurable responses
  • Version Management - Handle multiple API versions seamlessly

Support

License

BSD 3-Clause

Clone this wiki locally