Skip to main content

How It Works

flAPI simplifies the process of creating data APIs into three straightforward steps. This effectively decouples high-throughput API consumers (like AI agents or web services) from traditional backend data systems, resulting in significantly improved performance and lower costs.

The Three-Step Process​

1. Connect Your Data​

Point flAPI to your data sources—whether they're cloud data warehouses like BigQuery and Snowflake, traditional databases like PostgreSQL, or file formats like Parquet and CSV.

# Example: Connect to multiple data sources
connections:
  bigquery-warehouse:
    init: |
      INSTALL 'bigquery';
      LOAD 'bigquery';
    properties:
      project_id: 'my-project'
      
  customers-parquet:
    properties:
      path: './data/customers.parquet'

What happens: flAPI leverages DuckDB's powerful extension ecosystem to connect to 20+ data sources out of the box. You can mix and match sources in a single API.

2. Define APIs with SQL​

Write standard SQL queries and define your endpoints using simple YAML files. Use Mustache syntax to create dynamic, parameterized queries.

Endpoint Configuration (sqls/customers.yaml):

url-path: /customers/
request:
  - field-name: segment
    field-in: query
    description: Filter by market segment
    required: false
template-source: customers.sql
connection:
  - customers-parquet

SQL Template (sqls/customers.sql):

SELECT
  c_custkey as id,
  c_name as name,
  c_acctbal as balance
FROM '{{{conn.path}}}'
WHERE 1=1
{{#params.segment}}
  AND c_mktsegment LIKE '%{{{params.segment}}}%'
{{/params.segment}}

What happens: flAPI automatically handles parameter validation, SQL injection prevention, and generates OpenAPI documentation.

3. Access Instantly​

Run the flAPI server and immediately access your data through secure, documented REST APIs—plus MCP tools for AI agents.

# Start flAPI
$ ./flapi -c config.yaml

✓ Loaded 12 endpoints
✓ Server listening on :8080
⚡ Ready in 1.2ms
# Call your API
$ curl http://localhost:8080/customers?segment=AUTO

{
  "data": [
    {"id": 1, "name": "Customer ABC", "balance": 7500.25},
    {"id": 2, "name": "Customer XYZ", "balance": 12300.50}
  ]
}

What happens: Your data is now accessible via a production-ready REST API with authentication, rate limiting, and automatic documentation.

The Architecture​

Why This Matters​

Problem: Direct Warehouse Access​

User Request → BigQuery → Wait 2-10s → $0.05 cost
(Every single request hits the warehouse)

10,000 requests/day = $500/day = $15,000/month

Solution: flAPI Serving Layer​

User Request → flAPI Cache → Response in 1-50ms → Free
(Warehouse queried once per hour)

Background: flAPI → BigQuery → Refresh cache ($0.05)
Total cost: ~$1.20/day = $36/month

Savings: 99.76%
Speed: 1000-20,000x faster

Key Benefits​

  • 🚀 Performance: Sub-millisecond responses instead of seconds
  • 💰 Cost Reduction: 90%+ savings on warehouse costs
  • 🔒 Security: Built-in authentication, rate limiting, row-level security
  • 🤖 AI-Ready: Automatic MCP tool generation for AI agents
  • 📦 Simple: Single binary, zero dependencies, local-first development

Next Steps​

🍪 Cookie Settings