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 |
|---|---|---|
|
string |
HTTP or HTTPS URL with a host; no URL user information, query, fragment, backslash, or whitespace. |
|
object |
Specify an authentication type below and its required fields. |
|
integer |
Required; 1–60 seconds. |
|
object[] |
Global request headers, each containing string |
|
object[] |
Global query parameters, each containing string |
|
boolean |
Probe operations require true. |
|
string |
Endpoint path beginning with |
|
string |
GET or POST. |
|
object[] |
Request headers or query parameters for the current probe endpoint. |
|
string |
json or form for POST. Do not omit and assume JSON by default. |
|
string |
Valid JSON text; cannot be combined with form data. |
|
object[] |
Form name/value pairs for POST form. |
|
boolean |
If enabled for GET, requires nonempty valid json. If disabled, configuration decoding removes the GET JSON body. |
|
string |
Paired with success_value; selects a value in source JSON. |
|
string |
Valid JSON text. Both value and JSON type are compared; |
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 |
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 |
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.