# OpenAPI

Connect to any API with an OpenAPI/Swagger specification

- Category: APIs
- Runs in: the Phloem cloud

Connects any HTTP API with an OpenAPI specification, so Hamming can query its endpoints as tables with SQL.

## What Phloem reads
- **The specification** — from a URL or pasted in, JSON or YAML (OpenAPI 3.x)
- **List endpoints as tables** — every `GET` endpoint without path parameters, with the fields its response schema describes
- **Live responses** — each query calls the endpoints it names and follows the API's pagination

Phloem only sends `GET` requests.

## What you need
- The API's OpenAPI spec URL, or the spec itself.
- The base URL for requests, reachable from Phloem's cloud.
- A credential, if the API needs one: an API key, a bearer token, or a username and password.

## Connect
1. In the console, open **Connectors**, choose **Add connector**, then **OpenAPI**.
2. Enter **OpenAPI Spec URL**, or paste the spec into **Or Paste Spec Content**.
3. Enter **Base URL** and choose an **Authentication Method**:
   - **API Key** — **API Key / Token**, plus **API Key Header Name** (default `Authorization`) and **API Key Prefix** (default `Bearer`; empty for none)
   - **Bearer Token** — **API Key / Token**
   - **Basic Auth** — **Username** and **Password**
   - **No Authentication**
4. Optional: a **Test Endpoint** (e.g. `/health`) for the connection test. Without one, the test calls the spec's first list endpoint.
5. Test the connection, then save.

## What Hamming can do
- **Query** — SQL over the endpoints, one table each: join, filter and aggregate across them
- **Sample** — a few records from an endpoint

## Notes
- A query reads at most 1,000 records from each endpoint.
- Nested objects in a response become columns.
- Endpoints that need a path parameter (`/users/{id}`) or use a method other than `GET` are not offered as tables.

## Connection fields

| Field | Type | Required | Notes |
|---|---|---|---|
| OpenAPI Spec URL | Text | No | URL to OpenAPI 3.x JSON/YAML spec |
| Or Paste Spec Content | Text | No | Alternative to URL - paste spec directly |
| Base URL | Text | Yes | Base URL for API requests |
| Authentication Method | One of | Yes | How to authenticate with the API |
| API Key / Token | Secret | No | API key or bearer token for authentication |
| Username | Text | No | Username for basic authentication |
| Password | Secret | No | Password for basic authentication |
| API Key Header Name | Text | No | Header name for API key (default: Authorization) |
| API Key Prefix | Text | No | Prefix before key (e.g., 'Bearer', 'Api-Key', leave empty for none) |
| Test Endpoint | Text | No | Endpoint to test connection (optional) |