This version of the connector is outdated. Show recent version
The Advanced 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
,...). This is identical with the Rest API connector.
The Advanced Rest API connector includes addtional features not available with the standard Rest API connector.
-
If selected OAuth2 authentication, the configuration includes new option to select: Use basic authentication, where you can additionaly provide your credentials: User name and Password.
-
If request types: POST, PUT, or PATCH is selected, you are able to use new data content types: UrlEncoded and FormData.
DataContentType
Mame 4 type:
- JSON (defaultne vybrany) - znamena, ze do polozky Data se musi zadat data ve formatu JSON, napr.
{
"Name": "Jack",
"Surname": "Black",
"Companies": [
"Company1",
"Company2"
]
}
- XML - stejne jako JSON, ale musi to byt format XML, napr.
<?xml version="1.0" encoding="UTF-8"?>
<Persons>
<Person>
<Name>Jack</Name>
<Surname>Black</Surname>
<Companies>
<Company>Company1</Company>
<Company>Company2</Company>
</Companies>
</Person>
</Persons>
- UrlEncoded - do polozky Data se musi zadat data ve formatu standardu application/x-www-form-urlencoded, napr.
person=JackBlack&person=CarlNowak&company=Company1
- FormData - nezadava se nic do polozky Data (tato polozka neni ani viditelna), jsou tam dve klikacky:
- Plain Values - umoznuje pridat plain text values (zase ve formatu application/x-www-form-urlencoded), napr. viz obrazek - doda Borisko
- Files - umoznuje pridat attachmenty
Pozn.
- polozka Data umoznuje pouzit placeholdery na data ze vstupu:
- u data content type = XML, nebo JSON:
- ${input} - nahradi placeholder za kompletni cela vstupni data
- ${input.Name} - nahradi pouze hodnotu z polozky Name
- ${input.Name} ${input.Surname} - nahradi pouze hodnotu z polozky Name a polozky Surname
- u data content type = UrlEncoded: (obecny zapis: klic=value&klic1=value1&...)
- placeholdery (${input} - neni povolen) mohou byt pouze ve value
, napr. person=${input.Name}${input.Surname}&person=CarlNowak&company=Company1, klic musi byt vzdycky bez placeholderu (tzn. person)
- u data content type = FormData:
- placeholdery (${input} - neni povolen) mohou byt pouzity v Plain Values
pouze ve Value
, viz UrlEncoded
- placeholdery (${input} - neni povolen) mohou byt pouzity ve Files
jak v polozce Filename
tak i v polozce Content
(take ve forme multiplaceholderu - ${input.Name}${input.Surname})
- polozka Plain Values umoznuje v hodnote Value pouzit placeholder(y), ${input.Key}, ${input.Key}${input.SubKey}, ... - pokud bude konektor v rezimu Bulk a na vstupu budou 3 zaznamy, tak do dat se stejny klic vlozi 3x ale po kazde s nahrazenymi hodnotami z prislusneho radku na vstupu
- polozka Files umoznuje v hodnote Filename a Content rovnez pouzivat placeholdery (myslim, ze stejne jako Plain Values), stejne tak se budou zaznamy mnozit podle poctu radku na vstupu
Data
- viz popis u Data Content type
Accessing input data
If the input schema is selected, it's data can be accessed by following placeholders:
Placeholder | Description |
---|---|
${input} |
Replaced by whole input |
${input.property} |
Replaced by single cell of input |
Using placeholders
Placeholders can be used to dynamically create the contents of the request body
or to modify the configuration.
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}
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 with the HTTP request in the form of key/value pairs. For more information, see this link HTTP documentation.
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.
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}
Configuration
Advanced 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 headers
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
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}
Advanced Rest API endpoint
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
Advance Rest API output (ver. 1.0.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 |
#### Advance Rest API Header (ver. 1.0.0) |
Column | Data type | Allow null | Description |
---|---|---|---|
Key | String | No | Header name |
Value | String | Yes | Header value |
Release notes
4.0.0
- First release