Skip to content
background-image background-image

This version of the connector is outdated. Show recent version

rest_api_connector

Rest API Connector

  • Version

    3.0

  • Agent restriction

    None

  • Processing type

    Row by row & Bulk

  • Multi-input step

    Not Supported

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,...).

DataContentType

The format that will be used for the content of the request body and also for the response (Content-type and Accept will be set to application/xml by default). To override the preferred response body format, use the Headers configuration section and insert the Accept key with the value application/xml to use JSON as the preferred response body format.

Data

The request body, which should be of the type defined in the DataContentType field (XML, JSON,...) or defined using the Content-Type HTTP header, which can be filled in the Headers property.

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 the ObjectID 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

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.

RestAPIConnection

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}

search: exclude: true

Rest API Endpoint configuration

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 response body
Content-type application/json format of content body

Endpoint

The path endpoint with the parameters for querying the requested resource from Host defined in the connection configuration.

api/endpoint/getData?dataId=1

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.

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 or application/xml 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 the ObjectID 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}
}
or 
${input}

Throw Error on NonSuccess response

Throw error for non 2xx response.

Output Format

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

Output Encoding

The character encoding used to convert bytes to text.

Input & Output Schema

Input

Input is optional

Output

The result of the API call is stored in the Content or ContentText of the output schema.

There are two possibilities for output data format:

  • Base64 - data will be Base64 encoded and returned into output property Content
  • Text - data will be encoded with selected OutpuEncoding into output property ContentText

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.

search: exclude: true

Rest API output (ver. 2.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

PostCZ API Endpoint configuration

Timeout

Define timeout in seconds. Default timeout is set to 100 seconds.

Body

Request body in which input data can be referred by using placeholders. Body is specific for selected request method. See documentation for more details.

Method

Following table shows supported request methods with links to more details about body and return types of requests:

Method Path Documentation
GET SendParcels sendParcels/idTransaction/{idTransaction} Detail
GET Stats sendParcels/stats Detail
GET ParcelDataHistory parcelDataHistory/parcelID/{parcelID} Detail
GET LetterWithCn22 letterWithCN22/idTransaction/{idTransaction} Detail
GET Location location/idContract/{idContract} Detail
POST SendParcels sendParcels Detail
POST ParcelPrinting parcelPrinting Detail
POST ParcelService parcelService Detail
POST ParcelStatus parcelStatus Detail
POST LetterWithCn22 letterWithCN22 Detail
POST Location location/idContract/{idContract} Detail
DELETE Location location/idContract/{idContract} Detail

Transaction ID

Transaction ID assigned by the B2B module.

Contract ID

ID CCK of submitter. In case of non-completion, the submitter is the caller.

Parcel ID

ID of parcel.

Date From

Date From in yyyy-MM-dd format.

Date To

Date To in yyyy-MM-dd format.

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

Release notes

3.0.3

  • Fixed shared nuget package versions.

3.0.2

  • Fixed right processing of nullable properties.

Was this page helpful?

Privacy Policy

©Integray 2024

Privacy Policy