One PostgREST-compatible API over heterogeneous data sources.
Register foreign servers and tables once (PostgreSQL metadata or drivers.yaml), then query HTTP APIs, databases, object storage, or local files through the same REST surface your frontend already knows — filters (id=eq.1), select, order, limit, RPC, and PostgREST error codes.
Client → /rest/v1/{table} → driver → remote source
cp .env.example .env # DATASPAN_VAULT_KEY=$(openssl rand -base64 32)
make postgres-up && make runOpen http://localhost:3020/rest/v1/ for runtime OpenAPI (application/openapi+json)
Run everything in Docker: deploy/ (make compose-up).
| Method | Path | Example |
|---|---|---|
| GET | /rest/v1/{table} |
Accept-Profile: public · ?id=eq.1&select=id,name |
| POST | /rest/v1/{table} |
Content-Profile: public · JSON body |
| PATCH | /rest/v1/{table} |
Content-Profile: public · ?id=eq.1 + body |
| DELETE | /rest/v1/{table} |
Content-Profile: public · ?id=eq.1 |
| POST | /v1/rpc/{function} |
remote procedure |
/rest/v1/ is an alias for Supabase JS database client (.from() / .rpc()). Auth, Storage, and Realtime are not provided.
PostgREST-compatible extras: .single() / .maybeSingle() (Accept: application/vnd.pgrst.object+json), Prefer: count=exact, bulk insert (JSON array body), PATCH/DELETE return 204 unless Prefer: return=representation.
Set DATASPAN_ANON_KEY to require apikey + Authorization: Bearer on the data API (optional JWT via DATASPAN_JWT_SECRET). No row-level security — gateway auth only.
Errors follow the PostgREST shape (code, message, details, hint) — e.g. PGRST205 when a table is not registered, PGRST301 for auth failures.
Register metadata before querying the data API (db mode only; use drivers.yaml in file mode):
POST /admin/api/credentials— encrypted secrets (or inline onPOST /admin/api/servers)POST /admin/api/servers— foreign server + protocol (+ optional inlinecredential)POST /admin/api/tables— table + column mapping (name→remote_name)POST /admin/api/functions— RPC mapping
GET /health (liveness) · GET /health/ready (meta store ping)
Protocols: http, postgres, mysql, mongo, redis, s3, file, and SaaS presets (notion, firebase, airtable, sheets). See docs/drivers.md.
| docs/ | Architecture, store modes, drivers |
| deploy/ | Docker images & compose |