Configure REST API Operations

Last updated: October 5, 2026Applies to current supported NIM releases

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}" }
}

An iteration filter selects rows using attribute, operation, and, when applicable, value. attribute is a JSON path relative to the row without $.. Set operation to contains, equals, truthy, exists, or regex. Use value for the comparison value or regular-expression pattern; truthy and exists do not use it.

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. 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 retrieval calls running concurrently. 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.