Description

The RESTDirectoryV2Receiver traverses one or more payload sub-directories. For each file found, it creates request headers and payload, passes generated data to the given target, and, upon receiving a response, stores the response payload to a file. This Receiver requires an XML configuration file to read the request URL and header metadata to create request headers. 


This Receiver sends the payload in the body of the request, so by default, it always makes a POST request. However, a GET or PUT request may also be used. To do so, the user must define the method as 'GET' or 'PUT' within the configuration file (discussed later in this article).


Payload data can be read from multi-level sub-directories. Example directory paths shown below: 

  • Windows payloadSubDir = subDir1\subDir2\data
  • Linux/Mac payloadSubDir = subDir1/subDir2/data


Note: This Receiver can also be used to make a SOAP request to a SOAP endpoint (i.e., URL). 'XML' must be chosen for the request and response content type parameters (see below). 



In This Article

Receiver Parameters

The following parameters can be defined for the RESTDirectoryV2Receiver. Items with an asterisk (*) are required.  

  • payloadFilesPath* - Defines the base location of the files to send. 
  • payloadFilesSubDir* - Defines the naming convention for sub-directories within the payloadFilesPath.
  • configFilePath* - Defines the location of the configuration file.
  • configFileSubDir - Defines the sub-directory within the config directory. 
  • configFileName* - Defines the name of the configuration file.
  • configTag* - Defines the tag that needs to be matched from the list of configurations defined in the file.
  • loginIteration - Defines the number of iterations after which a login request needs to be made to authorize the token.
  • requestContentType* - Defines the HTTP content type for the request:
    • ANY, TEXT, JSON, XML, HTML, URLENC, BINARY
  • responseContentType* - Defines the HTTP content type for the response:
    • ANY, TEXT, JSON, XML, HTML, URLENC, BINARY
  • responseOutput* - Defines if an output response file should be produced and, if so, how it should be produced.
  • responseFilePath - Defines the location where the response file will be saved.
  • responseFileSubDir - Defines the sub-directory within the response directory where the response file will be created.
  • responseFileName - Defines the name of the Response file.
  • logRequestCount* - Defines the number of requests that are executed before logging a message to the console.
  • threadCount* - Defines the number of requests that may be sent simultaneously.
  • requestsLimit - Defines the number of total requests that can be handled by the API.
  • requestsDuration - Defines the time (in seconds) in which it handles the value entered for the requestsLimit parameter.
  • scriptFilePath - Defines the path where the script file will be located. A script can be executed after receiving the response to take further actions.
  • scriptFileSubDir - Defines the sub-directory within the script directory. 
  • scriptFileName - Defines the name of the script to be executed.


Parameter Example for Throttling Incoming Requests

The threadCount, requestsLimit, and requestsDuration parameters can be used to throttle incoming API requests. See the example below: 


 

For this example, the requests will be sent in batches of 20 based on the thread count. Since the request limit is set to 100, 5 batches of 20 will be sent.


When a batch of requests is sent, a counter keeps track of the time spent sending those requests. The request duration is 60 seconds. If the time spent is 20 seconds, then it will wait for 40 seconds before starting with the next round of 100 requests. This will continue until all batches of API requests are finished.

Configuration File

The RESTDirectoryV2Receiver must read from a configuration file to attain the request URL and other request header information.


PUT Method for Sending Payload

When not defined in the configuration, this Receiver uses a POST method to send the payload in the body of the request by default. The user can define the method as PUT in the configuration file, as shown below:


<config tag="brand">
   <requestURL>https://abc.com/brand</requestURL>
   <method>PUT</method>
    <headers>
       <header type="constant" name="header1">value1</header>
       <header type="constant" name="header2">value2</header>
    </headers>
</config>



Sample Configuration File

The format of the configuration file is as follows using the default POST method:


<configs>
  <commonHeaders>
    <header type="timestamp" format="yyyyMMdd" name="Accept-Datetime"/>
    <header type="UUID" name="If-Match"/>
    <header type="constant" name="x-auth">n4vdslor8dnx0ghlnbg34rcn96bf</header>
  </commonHeaders>

  <config tag="organization">
    <requestURL>https://abc.com/organization</requestURL>
    <headers>
      <header type="constant" name="header1">value1</header>
      <header type="constant" name="header2">value2</header>
    </headers>
    <scripts>
      <parameter name="paramaterName1">value1</parameter>
      <parameter name="paramaterName2">value2</parameter>
    </scripts>
  </config>

  <config tag="brand">
    <parameter filePath="#{resource.output.directory}" fileName="org.props"/>
    <requestURL>https://abc.com/brand/#{ORG_ID}</requestURL> 
    <headers>
      <header type="constant" name="header3">value3</header>
    </headers>
  </config>

  <config tag="store">
    <parameter filePath="#{resource.output.directory}" fileName="brand.props"/>
    <requestURL>https://abc.com/store/#{BRAND_ID}</requestURL> 
    <headers>
      <header type="constant" name="header4">value4</header>
      <header type="constant" name="header5">value5</header>
    </headers>
  </config>

</configs>


Windows NTLM Authentication Support

When making a REST API call, you will need to add a ntlmAuth tag in the config file. A tag example has been provided below:


<configs>   
   <ntlmAuth>
             <user>someUserName</user>
             <password>somePassword</password>
             <domain>someDomainName</domain>
   </ntlmAuth>
<config tag="">
...
...
</config>
</configs>


What to do if your Request URL Contains an &

If your request URL has an &, you must replace it with this: &amp. If it is not included, you will receive an exception error. 


Original URL with &

<requestURL>https://someurl?fname=Jane&lname=Doe</requestURL>


URL in Configuration File

<requestURL>https://someurl?fname=Jane&amp;lname=Doe</requestURL>


Authorization - Steps for Obtaining Access Token 

Some REST API calls require a Login API call to get the token from the API request so you can use the token in further API calls. To do that, you need to specify a Login tag. The primary purpose of the loginIteration parameter and an optional login tag is to allow the user to get an access token for further API calls. 

  1. The login tag in the Config file will determine whether a login request is needed to get an access token. You do not need to create a Domain for the optional login tag when it is included in your configuration file.

  2. Then, the loginIteration parameter will determine how often a login request needs to be made (after how many requests).


Step 1 - Enter a value for the logIteration parameter

Enter a number value in the loginIteration parameter to represent the number of iterations before requesting a new token (e.g., 10, 100, 500).



Step 2 - Include the login tag in the configuration file

An optional login tag can be included within the configuration file for authorization. The login block in the file can be formatted in one of the following ways: 


User/Name Password

<login responseTokenName="accessToken">
    <requestURL>https://app.com/login</requestURL>

    <contentType name="response">JSON</contentType>
    <contentType name="request">JSON</contentType>

    <parameter name='username'>USER_NAME</parameter>
    <parameter name='password'>PASSWORD</parameter>
    <headers>
      <header type="constant" name="header1">value1</header>
      <header type="constant" name="header2">value2</header>
    </headers>
</login>


Secret Key/Access Key/Client Key

<login responseTokenName="accessToken">
   <requestURL>https://app.com/login</requestURL>

   <contentType name="response">JSON</contentType>
   <contentType name="request">JSON</contentType>

   <parameter name='secretKey'>SECRET_KEY</parameter>
   <parameter name='accessKey'>ACCESS_KEY</parameter>
   <parameter name='clientKey'>CLIENT_KEY</parameter>
   <headers>
      <header type="constant" name="header1">value1</header>
      <header type="constant" name="header2">value2</header>
   </headers>
</login>


Note: The parameters XML tag represents request parameters that may differ from customer to customer. There can be n number of Parameter tags, which vary based on request parameters.


Example Configuration with Login Block

<configs>
  <commonHeaders>
    <header type="timestamp" format="yyyyMMdd" name="Accept-Datetime"/>
    <header type="UUID" name="If-Match"/>
    <header type="constant" name="x-auth">n4vdslor8dnx0ghlnbg34rcn96bf</header>
  </commonHeaders>

 <login>
    <requestURL>https://stage.genrocket.com/home/login</requestURL>
    <parameter name="username">USER_NAME</parameter>
    <parameter name="password">PASSWORD</parameter>
    <headers>
      <header type="constant" name="header1">value1</header>
      <header type="constant" name="header2">value2</header>
    </headers>
  </login>

  <config tag="organization">
    <requestURL>https://abc.com/organization</requestURL>
    <headers>
      <header type="constant" name="header1">value1</header>
      <header type="constant" name="header2">value2</header>
    </headers>
  </config>

</configs>


Use Case 1 - Static URL in the Request URL

In this use case, the URL is static and does not change.

<requestURL>https://someURL</requestURL>


Example:

<requestURL>https://abc.com/brand</requestURL>


Use Case 2 - Dynamic URL in the Request URL

A dynamic URL can be provided within the <requestURL> portion of the configuration file. A dynamic URL allows the value to change for each request. 


A user can add any Attribute in the URL by enclosing it in #{ }, and the value will be replaced with the Attribute. The user must also set the Domain's include property key to 'true'. Its default value is 'false'.


In the example below, the <requestURL> includes a firstName and lastName Attribute, which will be read from the Attributes. 

https://someurl/#{firstName}/#{lastName}


A sample configuration file is shown below: 

<config tag="brand">
   <requestURL>https://some-URL/#{firstName}</requestURL>
   <method>PUT</method>
    <headers>
       <header type="constant" name="header1">value1</header>
       <header type="constant" name="header2">value2</header>
    </headers>
</config>


Use Case 3 - How to Configure Authorization Header Name for Token

The authorization token is necessary and automatically passed when utilizing the login tag. Upon invoking the login API from the config file using login tag data, all APIs inherit the authorization token. 


By default, the request header is set with the "Authorization" header with the Bearer token value. However, the user can configure the header name for the Bearer token value using the authorizationHeaderName attribute in the login tag (as shown below).

<login responseTokenName="accessToken" authorizationHeaderName="SomeValue">
    <requestURL>https://app.com/login</requestURL>
    <contentType name="response">JSON</contentType>
    <contentType name="request">JSON</contentType>
    <parameter name="username">USER_NAME</parameter>
    <parameter name="password">PASSWORD</parameter>
    <headers>
      <header type="constant" name="header1">value1</header>
      <header type="constant" name="header2">value2</header>
    </headers>
</login>


Use Case 4 - Reading Dynamic Headers

To read dynamic headers, you will need to include a contentType value, which is read from the configuration (properties) file. An example is provided below: 


<header name="Content-Type" type="constant">#{contentType}</header>