Skip to content

Latest commit

 

History

History
144 lines (108 loc) · 3.73 KB

getting-started.md

File metadata and controls

144 lines (108 loc) · 3.73 KB

Getting started

Goal: a working REST endpoint backed by your own SQL, in about five minutes.

You will not write any backend code. An endpoint is a YAML file plus a SQL file.


1. Install

pip install flapi-io     # installs both `flapi` (server) and `flapii` (CLI)

Or run the container, which needs nothing installed:

docker pull ghcr.io/datazoode/flapi:latest

Other options — release archives, building from source — are in the main README.

2. Create a project

flapii project init my-api
cd my-api

That scaffolds:

my-api/
├── flapi.yaml        # connections, server settings
├── sqls/
│   ├── sample.yaml   # an endpoint definition
│   └── sample.sql    # its SQL template
├── data/
│   └── sample.csv    # the data the sample endpoint reads; add your Parquet/CSV here
└── common/           # reusable auth / rate-limit snippets

3. Point it at your data

Edit flapi.yaml:

project-name: my-api

template:
  path: ./sqls

connections:
  my-data:
    properties:
      path: ./data/customers.parquet

A connection is any data source — a local file, S3, Postgres, BigQuery, Snowflake. See CONFIG_REFERENCE § 2.3 for every supported shape, and cloud storage for S3/GCS/Azure.

4. Define the endpoint

sqls/customers.yaml:

url-path: /customers
method: GET

request:
  - field-name: id
    field-in: query
    required: false
    validators:
      - type: int
        min: 1

template-source: customers.sql
connection: [my-data]

sqls/customers.sql:

SELECT * FROM read_parquet('{{{ conn.path }}}')
WHERE 1=1
{{#params.id}}
  AND customer_id = {{{ params.id }}}
{{/params.id}}

The WHERE 1=1 idiom lets each filter be added conditionally. The int validator is what types the field (field-type has no effect; startup warns if you set it). There is no LIMIT: GET responses are paginated by default (100 rows per page, ?limit= / ?offset=, {"next", "total_count", "data"} in the body), so a LIMIT in the template would cap what pagination can reach. See Building a REST endpoint for the template rules that matter — particularly the difference between {{ }} and {{{ }}}.

5. Run it

flapi -c ./flapi.yaml
curl 'http://localhost:8080/customers?id=123'

Open http://localhost:8080/doc for a Swagger UI generated from your config, and http://localhost:8080/doc.yaml for the raw OpenAPI document.

Want to use the flapii CLI too? It talks to the server's configuration service, which is off by default. Start with it enabled:

export FLAPI_CONFIG_SERVICE_TOKEN=dev-token-0123456789
flapi -c ./flapi.yaml --config-service

See CONFIG_SERVICE_API_REFERENCE.

Where to go next

You want to… Read
Add validation, pagination, more parameter types REST endpoints
Let an AI agent call this MCP tools
Make a slow query fast Caching
Require a token Authentication
Ship it as one binary Self-packaging
See traces and audit records Observability

How it works

A request enters a Crow middleware chain, resolves to an endpoint from a copy-on-write configuration snapshot, has its parameters validated, renders the Mustache template, executes on an embedded DuckDB, and serialises the result.