feat: Add OpenAPI Foreign Data Wrapper

[codybrom]

What kind of change does this PR introduce?

Two years ago, @kiwicopple opened #49 with a vision: what if you could query any REST API from Postgres, just by pointing at its OpenAPI spec? Then, 5 days ago, he closed it as completed. I was ecstatic when I saw the GitHub notification email, but unfortunately I couldn't find any PR or commit that implemented it so I decided to take a stab at it.

What this PR includes is a generic OpenAPI 3.0 FDW. Instead of writing a new wrapper for every REST API, you could point this at an OpenAPI spec and basically have it work out the tables for you.

This first version covers just the "read" part of what @kiwicopple suggested in #49 and implements GET requests as SELECTs using the OpenAPI spec to generate Postgres types for the responses. It also includes support for unauthenticated, bearer token or other header-based authentication (no support for OAuth flows - BYO-token).

What is the current behavior?

Every API needs its own FDW. Stripe has stripe_fdw, Shopify has shopify_fdw, etc. Each one has to handle pagination, auth, response parsing. You know... all the usual stuff.

I've been doing a lot of this work via plpgsql functions and pg_net/http extensions lately, and it gets old fast. Every new API means writing another function to handle its quirks.

What is the new behavior?

Point at a spec and query the API.

CREATE SERVER weather_api
FOREIGN DATA WRAPPER wasm_wrapper
OPTIONS (
    fdw_package_url 'file:///path/to/openapi_fdw.wasm',
    fdw_package_name 'supabase:openapi-fdw',
    fdw_package_version '0.1.0',
    base_url 'https://api.weather.gov',
    spec_url 'https://api.weather.gov/openapi.json'
);

-- One command generates tables for every endpoint
IMPORT FOREIGN SCHEMA openapi FROM SERVER weather_api INTO public;

-- Now query weather stations like they're local tables
SELECT * FROM stations LIMIT 5;

The NWS API returns GeoJSON, so setting up alerts requires digging into the nested structure:

CREATE FOREIGN TABLE zone_alerts (
    zone_id text,
    event text,
    headline text,
    severity text
)
SERVER weather_api
OPTIONS (
    endpoint '/alerts/active/zone/{zone_id}',
    response_path '/features',
    object_path '/properties'
);

SELECT event, severity, headline
FROM zone_alerts
WHERE zone_id = 'OKC143';

Result:

event	severity	headline
Extreme Cold Warning	Severe	Extreme Cold Warning issued January 25 at 10:15PM CST until January 26 at 12:00PM CST by NWS Tulsa OK

---

The FDW handles the stuff I got tired of reimplementing. Path parameters just work. Define an endpoint like /users/{user_id}/posts and the FDW substitutes from your WHERE clause. If you forget a required param, it tells you what's missing instead of just failing.

The FDW also auto-detects cursor-based, URL-based, or offset pagination and handles it transparently. It also does limit pushdown, so SELECT * FROM big_table LIMIT 10 stops fetching after 10 rows instead of pulling everything first. Rate limiting respects Retry-After headers when APIs send them, otherwise exponential backoff.

I also got tired of dealing with column name mismatches. Some APIs occasionally slip in some camelCase but since Postgres lowercases everything I made sure the FDW translates automatically (created_at matches createdAt). Same with schema composition, real-world OpenAPI specs might use allOf/oneOf/anyOf everywhere and this handles them. For GeoJSON or wrapped responses, there's response_path and object_path to dig into nested structures. And, maybe my favorite feature, any table can have an attrs column (jsonb) if you need the raw response.

For APIs that need auth, credentials can even be stored in the Vault (if you're on Supabase), or inline if you're not.

Scope

I started it read-only for now (GET -> SELECT). Write ops are stubbed. I figured it's better to get read working solid first and someone with a better use case for writes can add them later if people want them.

Additional context

• Implemented as a WebAssembly wrapper in wasm-wrappers/fdw/openapi_fdw/
• Has 10 unit tests + integration tests all passing
• Most thoroughly tested against the weather.gov API (my use case)
• Includes docs at docs/catalog/openapi.md

This is my first PR on this project so please let me know if anything needs changed or fixed.

---

Partially addresses #49

[Copilot]

Pull request overview

This PR adds a generic OpenAPI 3.0+ Foreign Data Wrapper that allows querying any REST API with an OpenAPI specification directly from PostgreSQL. The implementation is read-only and supports GET operations with automatic pagination, rate limiting with retry logic, path parameter substitution, and IMPORT FOREIGN SCHEMA for automatic table generation.

Changes:

• Added new openapi_fdw WASM wrapper with OpenAPI spec parsing, schema generation, and FDW implementation
• Integrated the new FDW into the workspace build system and main README
• Added comprehensive integration tests and mock API server endpoints
• Provided user documentation and developer README with examples

Reviewed changes

Copilot reviewed 12 out of 13 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
wasm-wrappers/fdw/openapi_fdw/src/lib.rs	Main FDW implementation with request handling, pagination, and data mapping
wasm-wrappers/fdw/openapi_fdw/src/spec.rs	OpenAPI 3.0 specification parsing with schema resolution and composition support
wasm-wrappers/fdw/openapi_fdw/src/schema.rs	PostgreSQL schema generation and type mapping from OpenAPI schemas
wasm-wrappers/fdw/openapi_fdw/wit/world.wit	WASM component interface definition
wasm-wrappers/fdw/openapi_fdw/Cargo.toml	Package configuration and dependencies
wasm-wrappers/fdw/openapi_fdw/README.md	Developer documentation with build and test instructions
wasm-wrappers/fdw/Cargo.toml	Updated workspace to include openapi_fdw
wasm-wrappers/fdw/Cargo.lock	Dependency lock file updates
wrappers/src/fdw/wasm_fdw/tests.rs	Integration tests covering various endpoint patterns and features
wrappers/dockerfiles/wasm/server.py	Mock API server endpoints for testing
docs/catalog/openapi.md	Comprehensive user documentation with configuration and usage examples
README.md	Added OpenAPI FDW to the main wrapper list
.vscode/extensions.json	VS Code extension recommendations

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[codybrom]

I've addressed all the Copilot feedback in a follow-up commit. Happy to squash if you'd prefer a single commit.