Configure REST Requests

Step 1 · REST settings

Set the shared request behavior once, then override it only where an API endpoint needs something different.

The minimum working configurationDirect link to The minimum working configuration

Define rest.config with the base URL, authentication, default GET behavior, and a lightweight connection test.

"rest": {
  "config": {
    "baseUrl": "https://api.example.com/v1",
    "authentication": "client_credentials",
    "call_handling": "generic",
    "get": {},
    "test_connection": { "url": "/me" }
  },
  "authOptions": {
    "type": "client-credentials",
    "authUrl": "https://identity.example.com/oauth/token"
  }
}

Configure in this orderDirect link to Configure in this order

1. Endpoint and API handlingDirect link to 1. Endpoint and API handling

Set baseUrl to the shared API base path. Use call_handling: "generic" unless you are building a dedicated Google or Azure connector. Add global headers, accept, socket_timeout, or maxCallsPerMinute only when the API requires them.

2. AuthenticationDirect link to 2. Authentication

Set authentication in rest.config, then add the matching options in rest.authOptions. Supported modes include Basic authentication, Duo request signing, client credentials, certificate, JWT, Aeries, custom POST token, Digest, authorization-code grant, and password grant. Follow REST connector authentication for configuration instructions and examples.

Keep secrets in NIM connection values; reference them in the connector rather than placing credentials in source control.

When the API uses OAuth, follow its documented grant and token requirements. RFC 9700, OAuth 2.0 Security Best Current Practice explains why grant choice, token handling, and redirect URI validation matter. Prefer an API-supported flow appropriate to an unattended connector, and avoid the password grant for new designs; do not assume every API or NIM connector uses OAuth.

3. Read behaviorDirect link to 3. Read behavior

Configure defaults under rest.config.get:

Setting	Use it for
`pagination`	APIs that return results in pages.
`selector`	Sending selected NIM columns to an API's field-selection parameter.
`queryParameters`	Shared query-string parameters. Prefer this camelCase property over deprecated `query_parameters`.
`maxPageCount`	Limiting pages during collection or testing.

Set an operation's pagination to "none" when it must bypass the default.

Pagination modes and stopping conditionsDirect link to Pagination modes and stopping conditions

Put shared pagination under rest.config.get.pagination. An operation's pagination replaces it when an endpoint uses a different paging contract.

`mode`	Options and behavior
`generic`	Page-number pagination. Set `params` with `{page_number}`, `page_size`, and `zero_based` as required. `totalAttribute` reads the total record count; `totalPageAttribute` reads the total page count. Both are response JSON paths without a leading `$.`. With a page size, a short page signals completion.
`skip_take`	Offset pagination. Use `{skip_count}` and `{take_count}` in `params`; `page_size` determines the offset increment. A short page signals completion.
`link`	Follow the response's `Link` header to the next page. Set `page_size` and `zero_based` when required.
`url`	Follow a next-page URL from `field`, or construct it with `url_part`. Specify one of those properties. `replace_in_url` controls replacement behavior; `{page_number}` in `url_part` is always replaced. Add `query_params` and `last_page` when the API requires them.

page_size accepts a number or a connection substitution such as "{page_size}". The keys of params are the vendor's query parameter names; they are not NIM option names.

"pagination": {
  "mode": "skip_take",
  "page_size": "{page_size}",
  "params": { "offset": "{skip_count}", "limit": "{take_count}" }
}

For URL pagination, query_params is an array of entries with name and value. Each value has type: "constant" with a literal value, or type: "response_field" with a response JSON path in value. A last_page object uses either {"type": "field", "name": "isLastPage"} to stop on a true flag, or {"type": "token", "path": "nextToken"} to stop when the token is false, null, or absent.

Examples include Ellucian Cloud for offsets, GitHub for link headers, and Skyward Qmlativ for response-driven URL pagination.

Field selection and optional query parametersDirect link to Field selection and optional query parameters

selector.mode: "objects" sends a comma-separated selection through the query parameter named by parameter. selector.mode: "array" uses the name in array, for example fields[0]=name&fields[1]=email. Array selectors can specify excludedFields. Use selector: {"mode": "none"} when an endpoint must not receive a selection parameter.

queryParametersConfig: {"doNotSendIfEmpty": true} under rest.config.get, or an operation's call, omits parameters whose resolved values are undefined, false, or an empty string. This is useful for optional filters; it also means a boolean false value will not be sent.

4. Reliability and testingDirect link to 4. Reliability and testing

test_connection.url is required. Choose a safe, inexpensive endpoint that requires the same authentication as normal requests. Use retry for retry-after responses, connection errors, or explicit status codes. Prefer bounded retry counts when an API can remain unavailable.

Retry rulesDirect link to Retry rules

rest.config.retry is an array of rules. Each rule chooses a trigger with type:

Trigger	Configuration
`connectionError`	Retry connection failures.
`retryAfter`	Handle responses carrying a `Retry-After` header.
`statusCode`	Match the numeric `statusCode`. Optional `filterPath` and `filterValues` narrow the rule by a value in the processed response. `filterPath` is prefixed with `$.`; `_errorData.result` accesses the raw response data.

Each rule's nested retry selects type: "simple" with waitTime in seconds, or type: "exponential" with optional timeSlice and ceiling in seconds. Both accept maxCount. Omitting retry assumes an empty exponential configuration; omitting maxCount leaves retries unbounded.

"retry": [{
  "type": "statusCode",
  "statusCode": 429,
  "retry": { "type": "simple", "waitTime": 10, "maxCount": 5 }
}]

Transport and provider settingsDirect link to Transport and provider settings

`rest.config` option	Purpose
`accept` / `headers`	Set the accepted response media types and shared request headers.
`socket_timeout`	Connection timeout in seconds.
`maxCallsPerMinute`	Limit calls to this REST system per minute. Operation concurrency is configured separately with `maxSessionCount`.
`postAsForm`	Send the request body as `application/x-www-form-urlencoded`.
`no_keep_alive`	Disable connection keep-alive when needed by the endpoint.
`sslLegacyProtocols`	Permit legacy SSL protocols; false by default. Use only for endpoints that require them.
`wizard`	Graph-based connector setup. Set `type: "entra"` and the required `permissions`; see the Azure AD connector for an example.

Override per operation only when neededDirect link to Override per operation only when needed

An operation can extend authentication options and override headers, pagination, selectors, processing, compression, and request behavior. Keep common settings here; endpoint-specific details belong in operations.