Skip to content

Latest commit

 

History

History
124 lines (95 loc) · 6.77 KB

README.md

File metadata and controls

124 lines (95 loc) · 6.77 KB

flAPI documentation

flAPI turns SQL templates and YAML into REST APIs and MCP tools. These docs are organised by what you are trying to do. Each guide gets you working, then links to the reference for every option and to spec/ for how it works inside.

New to flAPI? Start with Getting started.


I want to…

Get something running

Goal Start here
Install flAPI and serve my first endpoint guides/getting-started.md
Understand the config file layout CONFIG_REFERENCE.md § 1
Run the server with the right flags CLI_REFERENCE.md

Build an API

Goal Start here
Add a REST endpoint guides/rest-endpoints.md
Write a SQL template safely guides/rest-endpoints.md#writing-the-sql-template · CONFIG_REFERENCE.md § 9
Validate incoming parameters CONFIG_REFERENCE.md § 5
Reuse config across endpoints, or read secrets from the environment guides/yaml-includes.md
Read from S3, GCS or Azure guides/cloud-storage.md

Expose it to an AI agent

Goal Start here
Turn an endpoint into an MCP tool guides/mcp-tools.md
Look up an MCP method, error code or capability MCP_REFERENCE.md
Manage configuration through MCP tools MCP_CONFIG_TOOLS_API.md · MCP_CONFIG_INTEGRATION.md
Build, cache and run flAPI with Claude Code (plugin: skills, slash commands, MCP, hooks) guides/claude-code.md

Make it fast

Goal Start here
Cache an expensive query guides/caching.md
Choose full refresh vs incremental guides/caching.md#choosing-a-refresh-strategy
Handle deleted rows in an incremental cache guides/caching.md#deletes-in-merge-mode
Rebuild a cache from scratch, or understand when it refreshes guides/caching.md#when-it-refreshes
Measure and shorten cache refresh time guides/caching.md#measuring-and-tuning-refresh-time
Understand cache snapshots and time travel spec/components/caching.md
Run on Cloud Run / scale-to-zero without loading data at startup guides/serverless.md

Secure it

Goal Start here
Require authentication guides/authentication.md · CONFIG_REFERENCE.md § 7
Restrict an endpoint by role guides/authentication.md#roles
Understand the layered defences spec/components/security.md

Operate it

Goal Start here
See request counts, error rates, latency and cache refresh times OBSERVABILITY.md § Runtime metrics · flapii metrics
Trace requests, find a slow one, join logs to traces OBSERVABILITY.md
See where the time went inside a query OBSERVABILITY.md § 4
Get an id out of a failed request OBSERVABILITY.md § 7
Check that span export is working OBSERVABILITY.md § 9
Keep an audit trail OBSERVABILITY.md § 8 · CONFIG_REFERENCE.md
Change configuration at runtime CONFIG_SERVICE_API_REFERENCE.md
Understand what product telemetry flAPI sends, and turn it off ../TELEMETRY.md

Deploy it

Goal Start here
Ship one self-contained binary guides/self-packaging.md
Run in Kubernetes, serverless or air-gapped OBSERVABILITY.md § 6

Reference

Exhaustive, option-by-option. Reach for these once you know what you are looking for.

Document Covers
CONFIG_REFERENCE.md Every key in flapi.yaml and in an endpoint YAML
CLI_REFERENCE.md flapi server flags, subcommands, environment variables
MCP_REFERENCE.md The MCP protocol as flAPI implements it
CONFIG_SERVICE_API_REFERENCE.md The runtime configuration REST API and flapii
MCP_CONFIG_TOOLS_API.md The MCP configuration tools
MCP_CONFIG_INTEGRATION.md How those tools are wired together
CLOUD_STORAGE_GUIDE.md S3 / GCS / Azure in depth: every provider, auth and failure mode
OBSERVABILITY.md Tracing, audit and log correlation

How it works

Implementation deep dives. Read these when you are changing flAPI, debugging something strange, or deciding whether a design will fit.

Document Covers
spec/ARCHITECTURE.md The layers and how components fit together
spec/REQUEST_LIFECYCLE.md One request, end to end, REST and MCP
spec/DESIGN_DECISIONS.md Why things are the way they are, and what was rejected
spec/components/config-system.md Config loading, validation, the copy-on-write endpoint table
spec/components/query-execution.md Template rendering and DuckDB execution
spec/components/caching.md DuckLake caching internals
spec/components/mcp-protocol.md MCP dispatch, sessions, SEP-414 trace context
spec/components/security.md Auth, validation, and telemetry egress
spec/components/observability.md Span tree, request context, capture tiers, exporters

Elsewhere