REST

The REST connector allows advanced builders to connect to services that provide a REST API. REST is web service architecture that typically uses the HTTP protocol, identifies resources with a URL, and represents actions with HTTP methods (also called verbs) such as GET, POST, PUT, and DELETE.

REST standards such as Swagger can be very helpful in creating services that are easy to use and understand.

Note: This REST connector differs from Nintex Apps's existing REST (Legacy) connector. The previous REST connector stored endpoints within page XML and did not centralize the logic used to connect to the REST service.

Concepts

Expectations for the REST connector

This connector is primarily intended for connecting to stateless services where either of the following can be accomplished with HTTP verbs:

• Facilitating create-read-update-delete (CRUD) behaviors on tabular data
• Activating webhooks for actions to be run on a server

Nintex Apps assumes it has arbitrary, random access to the service and that responses are returned in consistent, parseable formats (JSON and XML). While connecting to stateful REST services may be possible, they may take additional builder/developer resources---and may not function as expected.

Prerequisites

To utilize this connector fully, you need at least a basic-to-moderate understanding of the following concepts:

• HTTP request methods and response status codes
• MIME types
• JSON vs XML payloads

You\'ll also need to be familiar with the following for your external system of choice:

• The individual endpoints for each type of operation and their expected HTTP method
• The expected request format (headers vs URL parameters vs request payloads)
• The expected response format
• Your chosen authentication method (OAuth, basic authentication, etc)

For more technical information, see RFC 9110 for HTTP semantics.

Create request templates to map API endpoints

The REST connector requires that the endpoints of your chosen API be replicated as request templates. These templates are a combination of HTTP verbs, request data, and the endpoint to send those requests to. This process creates a reliable schema that Apps can use to understand the API.

Create connection objects and connection actions to use in Apps

These templates are then configured to be used as either connection objects or connection actions.

• Connection objects represent a specific data entity or resource, similar to a table in a database. This data is then modified in Apps pages through models. Objects map request templates to methods. With templates mapped to methods, Apps knows how to create, read, update, and delete the data available via the API. You'll typically use objects with Form and Table components.
• Connection actions represent operations trigger some sort of operation or service instead of working with tabular data—like triggering notifications. You'll use these in action flows.

Using these concepts will allow you to integrate many types of APIs into your Apps pages in a scalable way—with builders freely using configured connections without having to navigate the intricacies of the connection's endpoints.

Parameters

Parameters are the dynamic pieces of your API endpoint requests. They are the pieces of data that point the API to a specific record or action—like the unique identifier of a record. They can appear in a few different places:

• URL paths: These often appear as a path segment in a URL, like example.com/post/{Id}
• Headers: These are typically key-value pairs as part the network request
• Query parameters: These appear as key-value pairs at the end of a URL, like example.com/post?Id=<value>
• Body parameters: These parameters appear in the JSON payload that accompanies the headers in the network request. In connection objects, these are specified as fields. In connection actions, these may be specified with body inputs.

Manage REST connections

Create, delete, and deploy connections

To create a REST connection in Apps:

1. Click Connections.
2. Click Create.
3. Enter general information for the connection:
   • Connector: REST (Beta)
   • Name: Enter a meaningful name that identifies the service you're connecting to.

     Note: Once created, REST connections cannot be renamed.

4. Click Next.
5. Enter the base endpoint URL.
   • Some REST services may require allowlisting the IP address sending the request. Take note of the IP address provided in this step if so, and then allowlist it within your service.
6. Click Save.

To delete a connection:

1. Click Connections.
2. Beside the connection you wish to delete, click More Options > Delete.
3. Confirm by click Delete.

To import and export REST connections, use the deployment UI. To facilitate deployment across environments, consider using connection variables .

Set connection properties

• General

• Base endpoint URL: This is the base URL of the connection. For REST services, this will be the first part of the URL, which should be the same for all endpoints in models pointed to this connection.

  As with the example above, this value will look similar to http://www.example.com/api/v1/ for most REST connections.

• Use proxy: Choose whether or not to use a proxy. By default, this option is selected. See here for more information on the implications of using a proxy.

• Authentication

• Authentication method: Configure the appropriate authentication settings for this particular connection. Click here for more information about authentication in Nintex Apps.

• Common request data

• Header, Query parameters, and Body data: Data added here will be sent to the API with each request. This is typically used for API keys and access tokens.

Create request templates

For each relevant endpoint in your API:

1. Go to Request templates.

2. Click Create request template.

3. Set the following properties for each endpoint based on the documentation

   1. Verb: The HTTP verb

   2. Endpoint: The URI to send requests to in order to complete them. This endpoint should only include the URL paths after the base endpoint URL you configured at the connection level.

   3. Summary: A brief explanation of the intent of the endpoint.

      This summary appears throughout the REST console, so ensure it's informative and easily understood.

   4. Description: An expanded text area for more nuanced information about the end point—consider placing any unique constraints or details for use.

4. Click Create.

This information can often be lifted directly from your API documentation.

Once created, request templates can be mapped to one or more objects and/or actions.

Parameters on request templates

The request template is created. However, most endpoints will need/expect parameters—areas where Apps provides a piece of data to the request so that it can do the expected action.

Some parameters are defined on the request template. Others are defined on the action/object due to how they are used in the designer. Values are defined on objects and actions.

The following parameters are available on request templates:

• Path (a segment of the endpoint URL)
• Header
• Query

Create connection objects

Connection objects serve as a way to tie together request templates, metadata, and other configurations to perform create, read, update, and/or delete operations on data.

To create an object:

1. Click Connection objects.
2. Click Create object.
3. Enter the basic properties for the object:
   1. Label and Label plural: Enter a meaningful name for the object, one that conveys the intended purpose to builders. This label appears as the object to select for page models—as well as within model label merge syntax.
   2. Object Id: Enter a meaningful API name for the object. This Id is used when working with more advanced features, like JavaScript snippets.
4. Click Create.

Once created, map request templates to one or more of the following operations:

• Query: Used to retrieve records, typically associated with the GET HTTP verb.
• Insert: Used to create records, typically associated with POST or PUT HTTP verbs.
• Update: Used to retrieve records, typically associated with PUT, POST, or PATCH HTTP verbs.
• Delete: Used to delete records, typically associated with DELETE HTTP verbs.

To associate a request template to an operation:

1. Click the method you wish to set.
2. Click Add request template.
3. Click the desired template.
4. Click Save.

Add fields

Once at least one method has been set to a request template, you can add the fields available on the resource represented by the object. Fields configured here will be available for use in models should be verified with your API documentation. If the API is pointing to tabular data, these fields represent the columns of that table.

Fields can be added via a sample response, using a test request, or manually. If you wish to add additional fields after creating some or setting a path to contents, go to More Options > Change path to contents.

Each field has the following editable properties:

• Label: The user-facing label of the field.
• Id: Determines the API name, used with model XML and required for field JavaScript API usage.
• Data type: Determines how the values are sent within a request to the API. This should match the format expected by the API. Consider the following examples:
  String: "true"
  Boolean: true
  Array: ["true"]
• Display type: Determines what type of field renderer is used to display the field within Apps components
• Id field: Determines if the field contains a unique, identifying value for each row. Most objects should use only one Id field.
• Required: Determines whether or not the field must contain data before any insert or update operations occur within a page.
• Read-only: Determines whether or not a field can be edited by end users.
• Help text: Determines the default text that appears to end users at runtime.

Add from a sample response

With this method, Apps parses a pre-populated response to parse the fields available. This is typically the recommended method for adding fields if the API provides sample responses for endpoints in its documentation. It doesn't require a functioning query method and doesn't require manual field creation.

1. Click From a sample response.
2. Click Configure.

3. Paste the sample response in the left pane. Apps parses the sample response and shows the available data in the right pane.

Note:  Sample responses must use double quotes on keys and strings. Unquoted keys or single quote strings will not work.

The right pane displays a selection UI for the returned response. In this view, select the array containing the objects you wish to use as rows. Apps parses the key-value pairs available within each object of the array, seeing each key as as a field. Each key-value's data type is display in this pane---whether it be an object { }, array [ ], string Tt, or number #.

If the response contains nested data, you can navigate that data to find the array containing what should be considered the rows of the object. Many endpoints don't require setting a path to contents, but it may be necessary if the desired object data is nested within the response.

By default the topmost level of the response hierarchy is selected (All data). If the desired rows are nested within a different array, click that array.

Once you've selected the appropriate array, click Save. All keys within objects are imported as fields.

Add from a test request

This method requires a working query method.

Apps will send a request to the API, display the returned response body, and then you can select which fields to add.

1. Click From a test query response.
2. Click Configure. The test request modal appears.
3. Set any necessary parameters or pagination options to receive the type of response you need to get the desired fields.
4. Click Send.

Once sent, the raw response data appears in the left pane in the Response tab. If you wish to debug the request, you can see what was sent in the Request tab in that pane.

The right pane displays a selection UI for the returned response. In this view, select the array containing the objects you wish to use as rows. Apps parses the key-value pairs available within each object of the array, seeing each key as as a field. Each key-value's data type is display in this pane---whether it be an object { }, array [ ], string Tt, or number #.

If the response contains nested data, you can navigate that data to find the array containing what should be considered the rows of the object. Many endpoints don't require setting a path to contents, but it may be necessary if the desired object data is nested within the response.

By default the topmost level of the response hierarchy is selected (All data). If the desired rows are nested within a different array, click that array.

Once you've selected the appropriate array, click Save. All keys within objects are imported as fields.

Add manually

In some cases it may be necessary to add fields manually through this method. Doing so requires writing an exact map to a field. It requires knowing the exact path to contents and field information before you begin.

1. Click Manually add fields.
2. Enter the path to contents. If the rows will be at the top-level of the API's responses, leave this field blank.
3. Click Save.
4. Go to More Options > Create field.
5. Set the field's properties as needed.
• If the field is nested even after setting path to contents, use dot notation in the Id property, like user.address.street.
6. Click Create.

Choosing a path to contents

Typically, Apps row is equivalent to an individual JSON object. Thus, a set of rows is typically an array. By choosing a path to contents, you are letting Nintex Apps know how to navigate to an array of JSON objects to find the data you wish to be represented as rows. Each JSON object at the path to contents destination will be treated as a single row.

When adding fields from a sample response or test query, you must choose which piece of the response payload represents the rows of data. If the data that Nintex Apps should see as a row is nested within a JSON object, then you must set a path to contents, which tells Nintex Apps the path to navigate to retrieve the contents of data.

Important:  If you change the path to contents for a request, you are adjusting *all* field relationships and potentially breaking them. Be sure of your path to contents and try not to update it once it's set.

Pagination

Pagination properties are set on the object's query method, and they determine how to query additional records as an additional page of rows. This is typically done with limit and offset parameters. Consult your API's documentation to determine which parameters best match the options below:

Pagination strategy: Determines how Apps should send the necessary information to the API to retrieve additional pages of rows.

• Offset: The offset from the list of available records to begin requesting more records. Sometimes referred to as count, page start, skip, start position, or other related terms by other services.
  • Offset parameter: Determines which part of the request Nintex Apps manipulates for offset-related values.
• Token: Used for APIs that generate unique tokens that represent a placemarker in the total number of records available for query—creating a unique identifier to continue from instead of hard-coding a specific set of next results.
  • Token location, Token property path, and Token format: Determine where in the request Apps should place the specified token information and how the token should be formatted
• Limit parameter: Determines which part of the request determines the amount of records to query. Sometimes referred to as count, page size, batch size, max results, or other related terms by other services.
• Sort parameter: Determines which part of the request specifies how to sort the records returned by the API's response.

Setting parameter values

Parameters provide information to the API to return a specific set of resources, which is the primary way end users specify what they'd like to see in an app. Parameters for objects can be set to a single specified value—meaning they are hardcoded and cannot be changed elsewhere—or they can be Set in Page Designer.

When a parameter can be set in the Page Designer, builders have more flexibility through model conditions. It's still possible to hardcode a value there, perhaps one specific to a single page's use case. It's also possible to control parameter values through model conditions. This is particularly important for query operations.

In other operations, parameters typically function based on context in these scenarios. An end user is working with records in a component, and Nintex Apps passes in the parameter values based on the context record.

On shared parameter labels

Path parameters are not mapped to a specific term in the API—instead they are referenced by whatever label is used in Apps when creating the path parameter. Thus it's important to be specific, especially for parameters that may appear similar to other parameters. This is especially important for Id parameters—e.g. use {user_id}instead of just {id}.

Because request templates are bundled together under an object, and multiple "Ids" can appear in a single request templates---having specifically named path parameters will help downstream when configuring objects.

When bundling request templates, the assumption is that the request templates are operations on the same type of data. Because of that, any identically named path parameters are treated as a single condition.

Consider the following as an example:

GET user/{user_id}
PUT user/{user_id}
DEL user/{user_id}

When used in a page within the Page Designer, the {user_id} parameter will appear as a single condition—set only once—because it's assumed that since the model is working with a single object, its parameter should be set once for the object instead of once-per-request.

Create connection actions

1. Click Connection actions.
2. Click Create action.
3. Enter the basic properties for the action:
   1. Request template: Select the appropriate template you wish to use for the action.
   2. Name: Enter a meaningful name for the action, one that conveys the intended purpose to builders who may use the action in Apps.
   3. Description: Enter a longer form description of the action, typically with usage guidance.
4. Click Create.

Parameters on actions

Path, header, and query parameters may all be configured on the action-level, but you may also configure parameters in the request body using body inputs. These inputs will then be filled with values in the Page Designer to make the action's request relevant to the use case within the page.

This is done by navigating to the Body tab and enabling Send request body. Once enabled, you can configure the request body to match the expected schema.

Note:  The Body setup tab isn't available for actions that use GET request templates.

This step will vary from endpoint to endpoint, but the basics are the same:

• Create body inputs for any values that may require user input or don't remain static. These inputs are placeholders for dynamic values.
• Set the format for the payload body—whether as a template or a JavaScript snippet
• Enter the template or snippet that represents how body payloads should be sent.

Create body inputs

1. In the Body input section, click Add.
2. Configure the input:
   1. Id: Enter a meaningful name, which will appear to builders in the Page Designer.
   2. Data type: Select the data type that best describes the expected data for the parameters.
   3. Description: Describe the input.
   4. Required: Set whether or not the input is required to execute the request associated with the action.
3. Click Save.

Formatting payloads

Payloads can be formatted with a template or with a JavaScript snippet.

For more basic payloads, where the body input can be easily set in the Page Designer, it's typically recommended to use a template. To do so, select to format With a template and then enter the structure in the template field. Body inputs are inserted using merge syntax in double brackets.

For example, consider a template like this, where several body inputs are used at the value of the key-value pairs:

        {
            "id": {{id_of_the_record}},
            "title": {{title_to_use}},
            "content": {{user_content}}
        }
                

For more advanced use cases it may be necessary to use JavaScript to format. This allows the use of JavaScript functions and expressions.

Select to format payload With a JavaScript snippet and then enter the snippet within the snippet field.

The params object is available for use within these snippets, which contains the following information:

• bodyParams
• headers
• pathParams
• queryParams

Troubleshooting

CORs errors

CORs errors can occur when the service you're connecting to does not recognize a request's origin, which generally happens when a data source does not use Nintex Apps's proxy. If you have control over the server resource, you may be able to resolve these errors. You'd need to go to the server and add your endpoints to an allowlist.

Generally, you'll want to use the proxy.

Ensure path parameters are properly typed within the request templates tab

You must manually type a path parameter in the endpoint textbox after adding it as a path parameter. Ensure they match.

Always type path parameter values

Nintex Apps assumes that all path parameters are required. Whether a parameter's value is set in the Page Designer or a set to a single specific value, ensure it has a value (unless your API for some reason expects an empty path element).