Home

API Dock

API Dock builds an API gateway from YAML files. Under one endpoint it proxies requests to remote HTTP APIs and serves SQL queries over Parquet/CSV files (local or in S3, GCS or over HTTPS) and PostgreSQL tables. Each remote or database gets its own URL prefix (/<name>/...), can be versioned (/<name>/<version>/... or /<name>/latest/...), and is described by one small config file. You run it with the api-dock CLI as a FastAPI or Flask app, or embed its RouteMapper in your own Python service.

Source: https://github.com/SchmidtDSE/api_dock · PyPI: api-dock

Page	Description
Getting Started	Install, api-dock init, a first remote and database, the CLI reference
Concepts	The mental model: remotes and databases, routes, tables, schemas, versions, engines, how a request flows
Configuration	The main config.yaml, every setting, the config folder layout, multiple configs
Versioning	Versioned remotes and databases, how latest is chosen, the version listing
Catalog Endpoints	The expose section: /databases, /remotes, /sources listings
Routing and Restrictions	Remote routes, allow-lists, restricted patterns, custom route mapping
Authentication and Cookies	Forwarding and injecting cookies, authentication methods, encrypted values
SQL Database Support	Database configs: tables, [[table]] references, routes, startup checks
Query Parameters	Filtering, repeated values, sorting/pagination, required params, direct responses
Conditional SQL	Choosing a different base query from the request's query parameters
Shared Database Config	databases/config.yaml: global tables, schemas, slugs, shared routes
Cross-Schema Queries	Querying across schemas with [[*.table]] and schema groups
PostgreSQL	Serving PostgreSQL tables, natively or mixed with files
Lookups	Generating databases, versions and values from a query (SQL or HTTP), refreshed on a schedule
Python API and Deployment	Using RouteMapper in your own app, running in production
Developer Guide	Contributing, codebase layout, tests, release process

Quick start

pip install api-dock
api-dock init          # creates api_dock_config/ with commented example files
api-dock start         # serves api_dock_config/config.yaml on port 8000
curl http://localhost:8000/

Edit the generated files before relying on them: the examples point at placeholder URLs. Getting Started walks through a working remote and database.

At a glance

• YAML only. A main config.yaml lists the remotes and databases; each has its own file in remotes/ or databases/, or is written inline in the shared remotes/config.yaml or databases/config.yaml. See Configuration.
• Remotes are proxied. /<remote>/<path> is forwarded to the remote's url, with optional allow-lists, restrictions and route remapping. Under FastAPI the upstream response is streamed back. See Routing and Restrictions.
• Databases are SQL routes. Each route maps a URL pattern to SQL over tables declared in the config. Results are returned as a JSON list of rows. See SQL Database Support.
• Files and PostgreSQL. DuckDB queries Parquet/CSV files on local disk, S3, GCS or HTTPS. PostgreSQL tables (pip install 'api-dock[postgres]') run natively or alongside file tables. See PostgreSQL.
• Bound parameters. Path and query values reach the database as bound parameters, never pasted into SQL. See Query Parameters.
• Versioning. A folder of version files (or inline versions in remotes/config.yaml and slugs) makes /<name>/<version>/... and /<name>/latest/... available. See Versioning.
• Shared schemas and unions. Define tables once in databases/config.yaml, group them into schemas, and query across schemas. See Shared Database Config and Cross-Schema Queries.
• Lookups. Generate database/versions, remote versions or single values from a query over your tables or an HTTP API, refreshed on a schedule or on demand. See Lookups.
• Startup checks. API Dock checks every database config when it starts and refuses to start on a bad one, naming the database, version and route.
• Catalog endpoints. Optional /databases, /remotes and /sources list what is served. See Catalog Endpoints.
• FastAPI or Flask. api-dock start runs FastAPI by default; --backbone flask runs Flask (buffered responses, no PostgreSQL connections). See Python API and Deployment.