Configure REST API Operations

Last updated: October 26, 2026NIM service baseline: v3.0.1457

Data model · Operations

Define how NIM reads and changes one API object, then make only the approved fields available to mappings.

Start with one GET operation

Every table needs an operations object. Begin with collection, validate the result, then add write operations deliberately.

"operations": {
  "get_users": {
    "method": "get",
    "call": { "mode": "normal", "path": "/users" }
  }
}

The operation name is internal to the connector. Make it descriptive, such as get_users, create_user, or remove_group_member.

Choose an operation type

method	Typical purpose	Common semantic
get	Collect records or retrieve details	get
post	Create a record or invoke an API action	create
put	Replace or update a record	update
patch	Update selected fields	update
delete	Remove a record or relationship	delete

method is required. Use semantics to tell NIM what the call means; do not rely only on the HTTP verb when an API uses a non-standard pattern.

Build the request

call determines how NIM constructs and runs the request.

"update_user": {
  "method": "patch",
  "call": {
    "mode": "normal",
    "path": "/users/{id}",
    "queryParameters": { "notify": "false" }
  },
  "semantics": "update"
}

Use {resource_name} or connection-value substitutions in paths and payloads. Prefer call.queryParameters; query_parameters is deprecated.

Call modes

Mode	Use when
normal	One request handles the operation. This is the usual choice.
iteration	NIM must iterate another table and make a request for each value.
constant	The operation supplies fixed values instead of calling an API.

For an iteration call, define table, iterator, and path in addition to mode.

Iterate rows and carry context

table names the NIM table to iterate; iterator selects its iterator column. {iterator} in the path or base resolves to the current value. iterator_columns includes additional columns from that table, which can be substituted by name. base supplies an object whose iterator and extra-field substitutions are resolved for each call. This is useful when child responses omit the parent identifier.

"call": {
  "mode": "iteration",
  "table": "groups",
  "iterator": "id",
  "iterator_columns": ["displayName"],
  "path": "/groups/{iterator}/members",
  "base": { "group_id": "{iterator}", "group_name": "{displayName}" }
}

Filter iteration rows

Add filter inside an operation's call with mode: "iteration" to select which rows of the source table produce requests. NIM evaluates the filter against each iteration row before making the request; rows that do not match are skipped. This does not send a filter to the remote API or filter the returned response. Use call.queryParameters when the API itself must receive a query parameter.

The Google Workspace connector's Gmail labels operation iterates users and requests labels only for rows where isMailboxSetup is truthy:

"call": {
  "mode": "iteration",
  "table": "users",
  "iterator": "id",
  "filter": {
    "attribute": "isMailboxSetup",
    "operation": "truthy"
  },
  "path": "www.googleapis.com/gmail/v1/users/{iterator}/labels",
  "base": { "user_id": "{iterator}" }
}

This is the call excerpt, not a complete Google connector. For each matching user, {iterator} resolves to that user's id; base carries it into the collected row as user_id. The linked operation also configures Google authentication and response processing.

Filter property	Configuration
attribute	Required. A JSON path relative to the iteration row, without a leading $., such as isMailboxSetup or profile.mailbox.enabled.
operation	Required. One of contains, equals, truthy, exists, or regex.
value	A string comparison value for contains or equals, or a regular-expression pattern for regex. Not used by truthy or exists.

The REST Connector JSON Schema defines these operators:

Operation	Select a row when
contains	The attribute equals value, or an array attribute contains value. Comparison is case-sensitive.
equals	The attribute strictly equals value.
truthy	The attribute resolves to a truthy value. Use this for the mailbox flag in the example.
exists	The attribute path resolves to a value. This checks presence rather than whether a boolean flag is true.
regex	The attribute, or an element of an array attribute, matches the pattern in value. Supply the pattern without delimiters or flags.

Ensure the source table supplies the attribute used by the filter. Test with source rows that should match and rows that should be skipped, then verify the child collection. For the Google example, include users with isMailboxSetup set to true and false and confirm labels are collected only for the matching users.

Supply constant rows

For a constant call, supply values, an array of fixed row objects. These rows are vendor data rather than connector settings.

Headers and post-processing

Use call.extraHeaders for headers specific to this request. Values can contain connection substitutions such as {tenant}.

"call": {
  "mode": "normal",
  "path": "/users",
  "extraHeaders": {
    "accept": "application/vnd.example.v2+json",
    "X-Tenant-Id": "{tenant}"
  }
}

An accept header in extraHeaders replaces the accept value from rest.config for this call only. Use it when one endpoint needs a different response media type than the rest of the connector. The header name is not case-sensitive. Other headers are added to the request as usual.

call.queryParametersConfig.doNotSendIfEmpty omits query parameters that resolve to undefined, false, or an empty string.

Set call.post_processing to normal, child_tables, or as_input for the required post-processing mode. Configure the response output separately through the operation's processing_options. See PowerSchool and Google Workspace for examples of specialized post-processing.

Control what mappings can send

Collected resources are not automatically safe to write. Define mapping allowances for every write operation.

"create_user": {
  "method": "post",
  "call": { "mode": "normal", "path": "/users" },
  "semantics": "create",
  "resource_allowance_default": "prohibited",
  "resource_mandatory": ["firstName", "lastName"],
  "resource_prohibited": ["id"]
}

Property	Effect
resource_allowance_default	Sets the default mapping availability: optional, mandatory, or prohibited.
resource_mandatory	Requires listed resources in a mapping. For updates, only one resource can be mandatory.
resource_prohibited	Hides resources that an API must not receive.

Use body when the API needs a custom payload. _nim_merge_attributes_ in a body controls whether NIM merges mapping input into that payload. Use removeBlankFields, skipEmptyBody, or postAsForm only when the API contract requires them.

Set mergeOutput: true to merge the operation's result with the input data for POST, PUT, or PATCH. skipEmptyBody controls handling of empty POST objects or arrays. Set postAsForm: true for a POST or PUT endpoint that requires form-encoded input. Configure each option only on its supported operation type.

Set scimProtocol: true on a PATCH operation when the API requires an array of patch operations following RFC 7644 section 3.5.2. See SAP Concur for an example. Configure the remaining operations according to the target API's contract.

Handle API responses

For GET operations, configure pagination, selectors, and processing_options when the endpoint's response shape needs it. processing_options.output_field points to the result array or object; keyValue supports APIs that return one object of key/value pairs.

Operations can override the defaults in REST request settings, including authentication, pagination, headers, compression, and selectors. Keep common behavior in rest.config; override only the endpoint that differs.

Response shape and child references

Option	Purpose
processing_options.output_field	Locate the output using a response JSON path without a leading $.. The default is the table name; null selects the response root in the documented Google behavior.
processing_options.stringArrayColumnName	Name the column for a response containing an array of strings.
processing_options.keyValue	Turn a key/value object into rows. true uses columns named key and value; an object supplies keyColumnName and valueColumnName.
put_hash_in_child_tables	For GET, store each parent record's hash in the named child-table column so child rows can reference it.

Place processing_options beside call, not inside it. Instructure Canvas and Paycom illustrate string-array processing and child hash columns.

Retrieval limits and request overrides

Option	Supported use
maxSessionCount	GET retrieval concurrency: the maximum number of REST calls in flight at once while this operation collects data. The default is 1. The limit applies to all calls of the collection, including concurrent requests for different iteration values and pages fetched in parallel with total_count_header. Coordinate it with the shared maxCallsPerMinute limit.
maxPageCount	Limit pages for this GET operation. A small value is useful for testing and produces an incomplete collection.
verb	Override the HTTP verb of a GET operation when the vendor uses another verb to retrieve data. method still describes the NIM operation.
disableCompression	Omit the gzip accept header for an endpoint that cannot handle compression.
graphExcludedFields	For GET with call_handling: "azure", exclude fields from Graph's $select.
selector.excludedFields	Exclude fields from an array-mode selector.
warning_only	List numeric HTTP status codes to treat as warnings rather than errors. Choose only codes the API contract permits for this operation.

Operation-level query_parameters is deprecated on GET and is absent from the write-operation schema branches. Move query parameters into call.queryParameters, including on write operations. Operation authentication overrides are documented in REST connector authentication.

Safe delivery checklist

1. Test GET with a small data set and inspect every mapped resource.
2. Add one write operation with resource_allowance_default: "prohibited".
3. Permit only the fields required by the API contract.
4. Test with a disposable record and confirm the API result.
5. Configure warning-only status codes and bounded retries where the vendor documents expected transient errors.

Report a problem with this page

Found an error or a missing step? Open the feedback form and describe what needs changing. The article details and Documentation topic are filled in for you.

Need help with your NIM environment? Contact Support.