The Rest API Connector allows you to communicate with other REST services using the HTTP protocol with basic request types, i.e. GET
, POST
, PUT
, PATCH
and DELETE
. It also supports many of the most commonly used authentication methods (OAuth2
, Token
, NTLM
,...).
Configuration
Rest API connection
Base URL
The base URL of the connection. The request uses a combination of the Base URL
in this parameter with the Endpoint
URL path.
Base URL and Endpoint URL path in the System
If you input an absolute path into both the Base URL and Endpoint URL path, the system simply concatenates them as strings, potentially resulting in unsuccessful endpoint calls.
https://dx.xeelo.net
Input data can be referenced using placeholders, i.e. ${input.ObjectID}
will be replaced by the value in the ObjectID
property of the input. This placeholder only works when the input has a single line.
https:/server.com/${input.Uri}/
Ignore SSL Certificates
If set, will ignore SSL certificates. Can be used if the remote API does not have a signed certificate.
Authorization Method
Supported authorization methods:
- None - no authorization is used
- Basic - username and password (see Documentation).
- Token - authorization using a provided token
- OAuth2 - an authorization framework that exchanges credentials for an authorization token to be used (see Documentation).
- NTLM - Windows NT LAN Manager authentication protocol (see Documentation). Microsoft does not recommend NTLM for new implementations due to security concerns. It is used for backward compatibility.
- NTLM Ticket - More secure than just NTLM, credentials are negotiated for the access token. No need to send credentials for every request (see Documentation).
Username
Defines the login name that is used for connection authentication.
Input data can be referenced using placeholders, i.e. ${input.ObjectID}
will be replaced by the value in the ObjectID
property of the input. This placeholder only works when the input has a single line.
Password
Define the password that is used to authenticate the connection.
Input data can be referenced using placeholders, i.e. ${input.ObjectID}
will be replaced by the value in the ObjectID
property of the input. This placeholder only works when the input has a single line.
Domain
Define the NTLM domain that is used for connection authentication.
Input data can be referenced using placeholders, i.e. ${input.ObjectID}
will be replaced by the value in the ObjectID
property of the input. This placeholder only works when the input has a single line.
Authorization token
Define the authorization token that is used to authenticate the connection.
Input data can be referenced using placeholders, i.e. ${input.ObjectID}
will be replaced by the value in the ObjectID
property of the input. This placeholder only works when the input has a single line.
OAuth2 token endpoint
Define the OAuth2 token endpoint that is used to obtain the authorization token.
Input data can be referenced using placeholders, i.e. ${input.ObjectID}
will be replaced by the value in the ObjectID
property of the input. This placeholder only works when the input has a single line.
api/endpoint/token/${input.token}
OAuth2 token expiration
Define the expiration of the OAuth2 token in minutes.
OAuth2 request headers
Headers to include in the OAuth2 request. If no Content-Type
header is set, its value application/x-www-form-urlencoded
will be automatically included.
Input data can be referenced using placeholders, i.e. ${input.ObjectID}
will be replaced by the value in the ObjectID
property of the input. This placeholder only works when the input has a single line.
OAuth2 request body
Defines the body of the OAuth2 token request that is sent to the OAuth2 token endpoint.
Input data can be referenced using placeholders, i.e. ${input.ObjectID}
will be replaced by the value in the ObjectID
property of the input. This placeholder only works when the input has a single line.
NTLM ticket endpoint
Defines the NTLM ticket endpoint that is used to retrieve the authorization ticket.
Input data can be referenced using placeholders, i.e. ${input.ObjectID}
will be replaced by the value in the ObjectID
property of the input. This placeholder only works when the input has a single line.
api/ntlm/${input.Endpoint}/
NTLM ticket request beaders
Headers to include in the NTLM ticket request. If no Content-Type
header is set, its value application/json
will be automatically included.
Input data can be referenced using placeholders, i.e. ${input.ObjectID}
will be replaced by the value in the ObjectID
property of the input. This placeholder only works when the input has a single line.
NTLM ticket username
Defines the login name to be used to authenticate the NTLM connection ticket.
Input data can be referenced using placeholders, i.e. ${input.ObjectID}
will be replaced by the value in the ObjectID
property of the input. This placeholder only works when the input has a single line.
NTLM ticket password
Defines the password to be used to authenticate the NTLM connection ticket.
Input data can be referenced using placeholders, i.e. ${input.ObjectID}
will be replaced by the value in the ObjectID
property of the input. This placeholder only works when the input has a single line.
NTLM ticket domain
Define the domain that is used for NTLM connection ticket authentication.
Input data can be referenced using placeholders, i.e. ${input.ObjectID}
will be replaced by the value in the ObjectID
property of the input. This placeholder only works when the input has a single line.
NTLM ticket request body
Define the NTLM ticket request body that is sent to the NTLM ticket endpoint.
Input data can be referenced using placeholders, i.e. ${input.ObjectID}
will be replaced by the value in the ObjectID
property of the input. This placeholder only works when the input has a single line.
NTLM ticket request result path entry
The result path in the JSON response object where the NTLM ticket is returned, i.e. result.data
for the response:
{
"result":
{
"data": "string token"
}
}
Input data can be referenced using placeholders, i.e. ${input.ObjectID}
will be replaced by the value in the ObjectID
property of the input. This placeholder only works when the input has a single line.
result.data.${input.Property}
Request header ticket attribute
Defines the request header attribute key where the returned NTLM ticket will be stored.
Input data can be referenced using placeholders, i.e. ${input.ObjectID}
will be replaced by the value in the ObjectID
property of the input. This placeholder only works when the input has a single line.
${input.NTLMAttribute}
Rest API endpoint
Basic request types
The following table lists the supported HTTP methods. Additional configuration options are available based on the selected request type
Request type | CRUD |
---|---|
POST | Create |
GET | Read |
PUT | Update / Replace |
PATCH | Update / Modify |
DELETE | Delete |
Headers
Specify custom headers to be used in the HTTP request in the form of key/value pairs. For more information, see this link HTTP Headers.
It is not necessary to specify all headers, some are default based on the chosen data content type (Accept
, Content-Type
).
Header Key | Value | Description |
---|---|---|
Accept | application/json | format of response which will be received (requested API must support this) |
Content-Type | application/json | content body format to be used |
Endpoint
The endpoint specifies a Path
with parameters to query the requested resource from the Host
defined in the connection configuration. The combination of Host
and Path
is the requested URI.
Base URL and Endpoint URL path in the System
If you input an absolute path into both the Base URL and Endpoint URL path, the system simply concatenates them as strings, potentially resulting in unsuccessful endpoint calls.
Example
- api/endpoint/getData?dataId=1
- api/endpoint/create
Input data can be referenced using placeholders, i.e. ${input.ObjectID}
will be replaced by the value in the ObjectID
property of the input. However, except for the Data
configuration, this placeholder only works when the input has a single line.
Example
api/endpoint/${input.Method}
Timeout
The number of seconds to wait before terminating the request. The default value is set to 100.
Request Type
Supported HTTP request methods:
RequestType | CRUD |
---|---|
POST | Create |
GET | Read |
PUT | Update / Replace |
PATCH | Update/Replace |
DELETE | Delete |
DataContent Type
The format that will be used for the request body
when sending a request and also for the response (Content-type
and Accept
will be set to application/json
, application/xml
or application/octet-stream
by default).
XML Header
An XML header element to be added to the XML content in the request body
Example
<?xml version="1.0" encoding="UTF-8" ?>
XML Footer
An XML footer element that is added to the XML content in the body.
Data
The request body
, which should be in the format defined in the DataContentType
(XML, JSON,...) or defined using the HTTP Content-Type
header, which can be filled in the Headers
property.
Input data can be referenced using placeholders:
${input.ObjectID}
will be replaced by the value in theObjectID
property of the connector''s input data.- The
${input}
placeholder will be replaced by the integer value of the input data.
{
"Task": ${input.Task},
"IsActive": ${input.IsActive}
}
${input}
Octet-Stream (= Binary data)
You can use an octet-stream
to represent binary data. It is typically applied when the specific file type is unknown or when data is intended to be downloaded and saved. By using the application/octet-stream
type, you ensure that the data is treated as a sequence of bytes without any specific encoding.
Using placeholders
The placeholders can be used to access the input data and dynamically create the contents of the request body
or to modify the configuration.
If the input schema is selected, its data can be accessed by following placeholders:
Placeholder | Description |
---|---|
${input} |
Replaced by whole input |
${input.property} |
Replaced by a single property of input |
Input data can be referred by using placeholders:
${input.ObjectID}
will be replaced by the value in theObjectID
property of the input data connector.${input}
will be replaced by the integer value of the input data.
Placeholders for creating body content
The body content can be configured directly or can be generated based on the input using placeholders. The resulting JSON or XML (based on configuration) will also take into account the data type of the input columns. For example, the numbers in the JSON are as numbers (without double quotes).
Assume the connector input data is in the following format:
ID (Number) | Name (String) | Items (Complex) |
---|---|---|
1 | Alice | [{"ID":1},{"ID":2}] |
2 | Bob | [{"ID":3},{"ID":4}] |
Examples of using single cell
placeholders to create a request body
for the JSON
format. You can also serialize Complex
or JSON
types in this way.
{
"CustomerID": ${input.ID},
"CustomerName": ${input.Name},
"IsActive": true,
"ItemIDs": ${input.Items}
}
will generate request body
[
{
"CustomerID": 1,
"CustomerName": "Alice",
"IsActive": true,
"ItemIDs":
[
{"ID":1},
{"ID":2}
]
},
{
"CustomerID": 2,
"CustomerName": "Bob",
"IsActive": true,
"ItemIDs":
[
{"ID":3},
{"ID":4}
]
}
]
or whole body
placeholder
${input}
generates the following request body
that uses the property names as column names from the input schema
[
{
"ID": 1,
"Name": "Alice",
"Items":
[
{"ID":1},
{"ID":2}
]
},
{
"ID": 2,
"Name": "Bob",
"Items":
[
{"ID":3},
{"ID":4}
]
}
]
for input where there is only one line, the following placeholder
${input.Items}
generates an array of rows of type Complex
[
{"ID":1},
{"ID":2}
]
or XML
format supports single cell
placeholders so following settings
<Customer><Name>${input.Name}</Name></Customer>
will generate
<Customer><Name>Alice</Name></Customer>
<Customer><Name>Bob</Name></Customer>
with a combination of XML header
and XML footer
. It can generate the following XML where the Root
element Customers
is used.
<Customers>
<Customer><Name>Alice</Name></Customer>
<Customer><Name>Bob</Name></Customer>
</Customers>
Placeholders for other configuration properties
You can use the single cell
placeholder for other string configuration properties, which can be wrapped with additional text.
This allows you to dynamically change the path
of the request for the endpoint. But for these configuration properties, the placeholders
are replaced only by the first line of input data.
Example
api/endpoint/${input.Method}
Follow redirect
If this option is enabled, the web browser automatically redirects you to a new URL if redirection is detected on the page (for example, an HTTP 301 or 302 response). This setting can be useful to ensure that you are automatically redirected to the correct page when a URL change occurs.
Fail on error response
If this option is enabled, the application performing the query discards the server response if it returns an error code. In other words, throw error for non 2xx response. This option can be useful in situations where it is important to respond immediately to errors and not continue processing the query further.
Output Format Type:
Select returned data type:
-
Base64
- data will be returned as Base64 string -
Text
- data will be returned as plain text - use OutputEncoding property to set output data character encoding type -
JSON
- data will be returned as a JSON object
Output Encoding
The character encoding used to convert bytes to text.
Input & Output Schema
Input
Data schema is optional
The connector does not expect a specific schema. The required data structure can be achieved by correct configuration. Although the selected connector doesn't require a schema generally, the individual integration task step may need to match the output data structure of the preceding task step and use a data schema selected from the repository or create a new input schema.
Output
The result of the API call is stored in the Content
, ContentText
or ContentJSON
of the output schema.
There are tree possibilities for output data format:
Base64
- data will be Base64 encoded and returned into output propertyContent
Text
- data will be encoded with selected OutpuEncoding into output propertyContentText
JSON
- data will be encoded and returned into output propertyContentJSON
In addition to the content, the output also contains the StatusCode
and Headers
of the response.
For more information about status codes, see the document HTTP response status codes.
and the HTTP Headers headers.
Rest API output (ver. 2.1.0)
Column | Data type | Allow null | Description |
---|---|---|---|
StatusCode | String | No | HTTP response status code |
Headers | Rest API header 1.0.0 |
Yes | Received HTTP headers as key/value pairs |
Content | Base64 | Yes | Serialized content of HTTP response into Base64 |
ContentText | String | Yes | Serialized content of HTTP response into string |
ContentJSON | JSON | Yes | Serialized content of HTTP response into JSON |
Example output data for OutputFormat set to Base64
StatusCode: String |
Content: Base64 |
Headers: Rest API Header 1.0.0 |
---|---|---|
201 | ewogICAgIlN1Y2Nlc3MiOnRydWUKfQ== | Output headers data |
Output headers data
Key: String |
Value: String |
---|---|
Transfer-Encoding | chunked |
Connection | keep-alive |
Cache-Control | private |
Date | Thu, 17 Feb 2022 19:58:36 GMT |
Server | nginx/1.14.1 |
X-AspNet-Version | 4.0.30319 |
X-Powered-By | ASP.NET |
where decoded response Content
is:
{
"Success":true
}
Example output data for OutputFormat set to Text
StatusCode: String |
ContentText: String |
Headers: Rest API Header 1.0.0 |
---|---|---|
201 | { "Success":true } | Output headers data |
Output headers data
Key: String |
Value: String |
---|---|
Transfer-Encoding | chunked |
Connection | keep-alive |
Cache-Control | private |
Date | Thu, 17 Feb 2022 19:58:36 GMT |
Server | nginx/1.14.1 |
X-AspNet-Version | 4.0.30319 |
X-Powered-By | ASP.NET |
Example output data for OutputFormat set to JSON
StatusCode: String |
ContentJSON: JSON |
Headers: Rest API Header 1.0.0 |
---|---|---|
201 | { "Success":true } | Output headers data |
Output headers data
Key: String |
Value: String |
---|---|
Transfer-Encoding | chunked |
Connection | keep-alive |
Cache-Control | private |
Date | Thu, 17 Feb 2022 19:58:36 GMT |
Server | nginx/1.14.1 |
X-AspNet-Version | 4.0.30319 |
X-Powered-By | ASP.NET |
where decoded response ContentJSON
is:
{
"Success":true
}
Release notes
3.3.0
- Support OctetStream data content type.
3.2.2
- Fix right processing of BaseUrl and Endpoint configuration properties.
3.1.2
- This version introduces an extended logging interface that enables the logging of events.
Enhancements:
- New Log Hub Rules Template: Introduces the
Advanced REST API connector event - reconnect
, enhancing the connector's functionality. - Improved Logging for Reconnect Events: The connector now accurately logs the selected redirect message into the TaskRunLog. All essential information about reconnect events is now captured, facilitating easier monitoring and debugging for both company-level and admin-level users. With the introduction of multi-level logging, up to four entries may be recorded for a single event, providing a detailed view across user levels for improved transparency and troubleshooting.
3.0.3
- Fixed shared nuget package versions.
3.0.2
- Fixed right processing of nullable properties.