Skip to main content

Build a REST Connector

REST connector tutorial

Use the Skyward Qmlativ connector as a working pattern to build a new REST integration safely and incrementally.

What you will build​

You will create a connector that can:

  • authenticate to an API and confirm the connection;
  • collect one API object into a NIM table;
  • identify each record with a stable key; and
  • add a controlled write operation only after read collection works.

The Skyward Qmlativ connector repository is the reference example. It contains the connector JSON, its requested API access, many read-only tables, and a deliberately small set of create, update, and delete actions.

Before you begin​

  • Use a non-production API tenant and test records.
  • Obtain the vendor's API documentation and least-privilege credentials.
  • Install the connector JSON schema in your editor.
  • Choose one object to start with—for example, an employee or user—not the entire API.

1. Copy the connector shape, not its credentials​

Create a new JSON file with the root structure below. Keep secrets in NIM connection values or a secure secret store; never commit them.

{
  "$schema": "https://schemas.nimsuite.com/rest-connector.json",
  "schema": { "crud_objects": {} },
  "rest": { "config": {} },
  "connection": { "items": [] }
}

The Skyward example separates API access definition (IntegrationAccess.xml) from connector behavior (Skyward Qmlativ.json). Use the same separation: decide what the integration is allowed to do before implementing calls.

2. Make the connection test pass​

Configure rest.config with the API's base URL, authentication type, generic call handling, and a safe endpoint for test_connection.

"rest": {
  "config": {
    "baseUrl": "https://api.example.com/v1",
    "authentication": "client_credentials",
    "call_handling": "generic",
    "get": { "pagination": "none" },
    "test_connection": { "url": "/me" }
  },
  "authOptions": {}
}

Add tenant and client inputs under connection.items. See Design the connection screen for the supported controls and {name} substitutions.

Checkpoint: Add the system in NIM Studio and run the connection test before defining tables.

3. Model one table and collect it​

The Skyward connector has a large set of tables, but every one follows the same pattern: a table name, resources, a key where one exists, and operations. Begin with one.

"schema": {
  "crud_objects": {
    "employees": {
      "key": "id",
      "resources": {
        "id": "string*",
        "firstName": "string*",
        "lastName": "string*",
        "email": "string"
      },
      "operations": {
        "get_employees": {
          "method": "get",
          "call": { "mode": "normal", "path": "/employees" }
        }
      }
    }
  }
}

Use resources to map response fields and keys to choose the identifier. Configure pagination before collecting if the API can return more than one page.

Checkpoint: Collect the table, inspect the data, and confirm that the selected key is unique and stable.

4. Add writes with an explicit contract​

Skyward exposes writes only for approved objects and fields. Follow that practice: add create, update, or delete only when the API contract, authorization, and rollback plan are clear.

"create_employee": {
  "method": "post",
  "call": { "mode": "normal", "path": "/employees" },
  "semantics": "create",
  "resource_allowance_default": "prohibited",
  "resource_mandatory": ["firstName", "lastName"]
}

resource_allowance_default, resource_mandatory, and resource_prohibited control what a NIM mapping can send. Make optional fields explicit; do not make every collected field writable by default.

Checkpoint: Test one create with a disposable record. Verify the result in both the API and NIM before adding update or delete.

5. Extend deliberately​

Repeat the read-first pattern for each additional object. Add related tables only when a workflow needs them. If you need role-model memberships, model users, groups, and the membership table separately, then add group membership.

Before publishing, validate the JSON against the schema, document required API permissions, test paging and error behavior, and review every write operation with the system owner.

Next steps​

Last updated on