# Shared information for REST API sources

Draft probes, saved connector probes, and sample previews handle configuration and results separately. Probes access source verification endpoints; previews read source samples. Neither creates an import task or writes destination tables.

## Identity and configuration files

Use the target Workspace's personal access token, `WORKSPACE_ID`, and corresponding connector-operation privileges. Draft probes read a local configuration file: set `REST_CONFIG_JSON` to a JSON object file containing `rest_api`, and install jq. Examples place the file object in request `config`, not a JSON string.

For saved operations, `CONNECTOR_ID` comes from the same Workspace's connector list and must be active, have REST API source type, and support import. Saved operations use stored connection information and credentials; probe bodies cannot temporarily override them. Do not resubmit connector-detail echoes as draft secret configuration.

## Draft configuration

| Field | Type | Conditions and description |
| --- | --- | --- |
| `rest_api.base_url` | string | HTTP or HTTPS URL with a host; no URL user information, query, fragment, backslash, or whitespace. |
| `rest_api.auth` | object | Specify an authentication type below and its required fields. |
| `rest_api.request_timeout_seconds` | integer | Required; 1–60 seconds. |
| `rest_api.headers` | object[] | Global request headers, each containing string `name` and `value`. |
| `rest_api.params` | object[] | Global query parameters, each containing string `name` and `value`. |
| `rest_api.probe.enabled` | boolean | Probe operations require true. |
| `rest_api.probe.path` | string | Endpoint path beginning with `/`. Must not begin with `//` or contain backslashes, query, fragment, or whitespace. Use params for query parameters. |
| `rest_api.probe.method` | string | GET or POST. |
| `rest_api.probe.headers`、`params` | object[] | Request headers or query parameters for the current probe endpoint. |
| `rest_api.probe.body_type` | string | json or form for POST. Do not omit and assume JSON by default. |
| `rest_api.probe.json` | string | Valid JSON text; cannot be combined with form data. |
| `rest_api.probe.data` | object[] | Form name/value pairs for POST form. |
| `rest_api.probe.get_json_body` | boolean | If enabled for GET, requires nonempty valid json. If disabled, configuration decoding removes the GET JSON body. |
| `rest_api.probe.success_path` | string | Paired with success_value; selects a value in source JSON. |
| `rest_api.probe.success_value` | string | Valid JSON text. Both value and JSON type are compared; `true` differs from string `"true"`. |

| auth.type | Required fields | Optional fields |
| --- | --- | --- |
| none | No other required fields | None. |
| bearer | token | None. |
| api_key | name、api_key、location | location is header or query. |
| http_basic | username、password | None. |
| oauth2_client_credentials | access_token_url、client_id、client_secret、client_auth | client_auth is basic or body; configure scope and token_params (name/value pairs) as required by the source. |

Configure source authentication separately from ordinary request headers. Custom headers cannot set Host, Cookie, or Proxy-Authorization. When using the corresponding authentication, do not duplicate its authentication location in custom headers or queries. The source defines probe GET/POST behavior. Callers must confirm POST side effects in particular; a verification request is not necessarily read-only at the source.

## Preview endpoints and pagination

Previews use saved base_url and authentication. The current request defines only endpoint, extraction, and pagination settings. GET, OPTIONS, or POST with explicit `read_only_post: true` are available. Declaring read-only does not constrain the source service's own writes.

| pagination.type | Required fields | Description |
| --- | --- | --- |
| none | No other fields | No pagination. |
| page | param、start | start must be explicit and nonnegative. |
| offset | param、start、step | start must be explicit and nonnegative; step must be at least 1. |
| cursor | param、next_path | Path to the next cursor in the source response. |
| next_url | next_path | Path to the next URL in the source response; full import separately checks same-origin constraints. |

`total_path` can identify totals for numeric pagination. This preview reads only the first page and does not establish that later pages are readable. Pagination cursor is separate from optional `cursor_param`/`initial_cursor` incremental starting points; the latter pair must be supplied together.

Explicit Schema uses paired `schema_path` and `schema_format` (columns or json_schema). Handle mismatches between source declarations and records as errors, not ignorable type suggestions. Without explicit Schema, fields are inferred from samples. Suggested destination types do not establish table creation or completed column mapping.

Preview retrieves at most 20 records from the first page, with a 512 KiB total serialized-result limit. Returned records and fields are bounded samples, not proof that all source data was read. Do not first convert raw JSON numbers, such as wide integers or monetary values, to lossy client floating-point values.

## Errors and environments

| Situation | Response for this request | Handling |
| --- | --- | --- |
| Invalid configuration or an ineligible saved connector | Usually HTTP 400 `ErrParamInvalid`; authentication, resource, or service errors may use other statuses | Check configuration objects, authentication type, timeout, endpoint, purpose, and state. |
| Source rejection, record/Schema extraction failure, unmet verification conditions, oversized preview, timeout, or connection problems | HTTP 502 `ErrConnectorRESTRead` with localized information | The message may contain the source HTTP status. Interpret it separately from MOI HTTP 502; source HTTP 200 does not establish preview business success. |
| Localization or other internal service exception | May be HTTP 500 or the corresponding service error | Retain request information and handle the actual public error without depending on private Worker diagnostics. |

Worker request identifiers, execution states, and raw internal exceptions are not stable public response fields. Handler-local tests check the corresponding sanitized behavior. Preview `data.status_code` is the source status in a successful result.
