skip to main content
Quick Start: Accessing REST data sources using basic authentication : Creating an input REST File
  

Try DataDirect Drivers Now

Creating an input REST File

The driver supports an optional input REST file that allows you to specify multiple endpoints, define POST requests, and configure paging. You will need to create an input REST file if your session:
*Accesses multiple endpoints
*Issues POST requests
*Accesses endpoints that require paging
If your session does not require a REST file, you can specify your endpoint, for GET requests, using the Sample connection property instead. For sessions that use a REST file, you will need to create a REST file and specify its location using the Config property.
The input REST file is a simple text file that uses the file_name.rest naming convention. To configure the file, you will need to populate the contents with a list of comma-separated endpoints and requests using the formats described in this section. A sample REST file, named example.rest, is installed in the install_dir\restfiles directory. For additional examples, see "Sample Input REST File."
The following example demonstrates the basic format used in the REST file when mapping a table to the schema:
{
"<table_name1>":"<endpoint1>",
"<table_name2>":"<endpoint2>",
"<table_name3>":"<endpoint3>"
}

Specifying Endpoints for GET Request with Unparameterized Paths

To specify endpoints for unparameterized GET requests, use the following format:
"<table_name>":"<host_name>/<endpoint_path>",
table_name
is the name of the relational table to which the driver maps the endpoint. For example, country.
host_name
(optional) is the protocol and host name components of the URL endpoint. For example, http://mysite.com. You can omit this value by specifying the host name using the ServerName property.
endpoint_path
is the path component of the URL endpoint. For example, countries.
For example, the following demonstrates a GET request that will map to the countries table.
"countries":"http://mysite.com/countries/get/all",

Specifying Endpoints for GET Request with Parameterized Paths

To specify parameterized GET requests, use the following format:
"<table_name>":"<host_name>/<endpoint_path1>/{<param_name>:<param_value>}[/<endpoint_path2>]",
table_name
is the name of the relational table to which the driver maps the endpoint. For example, states.
host_name
(optional) is the protocol and host name components of the URL endpoint. For example, http://mysite.com. You can omit this value by specifying the host name using the ServerName property.
endpoint_path
is the path component of the URL endpoint. For example, states.
param_name
is the parameter identifier used for filtering the request. For example, countryCode.
param_value
is the parameter value used for filtering the request. For example, USA.
For example, the following demonstrates a GET request that will map to the states table.
"states":"http://mysite.com/states/get/{countryCode:USA}/all",

Specifying Endpoints for GET Requests with Query Parameters

Use the following format to specify endpoints for GET requests with argument parameters. Multiple argument parameters withing the same endpoint are separated by an ampersand (&).
"<table_name>":"<host_name>/<endpoint_path>?<parameter>=<value>[&...]",
table_name
is the name of the relational table to which the driver maps the endpoint. For example, timeseries.
host_name
(optional) is the protocol and host name components of the URL endpoint. For example, http://mysite.com. You can omit this value by specifying the host name using the ServerName property.
endpoint_path
is the path component of the URL endpoint. For example, times.
parameter
is the argument parameter component of the parameter=value pair used for filtering the request. For example, interval.
value
is the value argument parameter used for filtering the request. For example, 5min.
For example, the following demonstrates a GET request that will map to the timeseries table.
"timeseries":"https://www.mysite.com/times/query?interval=5min&symbol=USA&function=TIME_SERIES_WEEKLY",

Defining a POST Request

To use POST requests, you must define the request in the REST file in the JSON format. The definition entry is comprised of a path and body. The path contains the URL endpoint and the body used in requests, while the body defines documents and provides sample values. The driver then uses these sample values to define which data type to be used when executing a POST request. An entry for a POST request takes the following form:
"table_name": {
"#path": "<host_name>/<endpoint_path>",
"#post": {
"<field1>":"<value1>",
"<field2>":"<value2>",
}
},
table_name
is the name of the relational table to which the driver maps the endpoint. For example, countries2.
host_name
(optional) is the protocol and host name components of the URL endpoint. For example, http://mysite.com. You can omit this value by specifying the host name using the ServerName property.
endpoint_path
is the path component of the URL endpoint. For example, country.
document
is the document name of the document=value pair. For example, START_DATE.
value
is the sample value the driver uses to determine the data type to use when executing a POST to that document. For example, 2018-08-31.
For example, the following demonstrates an entry for a POST request that will map to the countries2 table.
"countries2": {
"#path": "http://mysite.com/country/get/all",
"#post": {
"start_date":"2018-08-31",
"end_date":"2018-09-01",
"departments":"[engineering,marketing,sales]",
"tags":"[blue,green,red]"
}
},

Configuring Paging

The driver supports two types of paging: offset and page numbering paging. To configure paging, specify values for the properties in the following tables that correspond to the type of paging you want to employ. Paging properties can be set for individual GET or POST requests by specifying these options in the body object. If paging properties are not specified, the driver will attempt to retrieve the first page for data sources that require paging.
The following demonstrates configuring row offset paging for an unparametrized GET request:
"table_name": {
"#path": "<host_name>/<endpoint_path>",
"#maximumPageSize":1000,
"#firstRowNumber":1,
"#pageSizeParameter":"maxResults",
"#rowOffsetParameter":"startAt"
},
table_name
is the name of the relational table to which the driver maps the endpoint. For example, countries2.
host_name
(optional) is the protocol and host name components of the URL endpoint. For example, http://mysite.com. You can omit this value by specifying the host name using the ServerName property.
endpoint_path
is the path component of the URL endpoint. For example, country.
Table 1. Row Offset Paging Properties
Property
Description
#maximumPageSize
The maximum page size in rows.
#firstRowNumber
The number of the first row. The default is 0; however, some systems begin numbering rows at 1.
#pageSizeParameter
The name of the URI parameter that contains the page size.
#rowOffsetParameter
The name of the URI parameter that contains the starting row number for this set of rows.
Table 2. Page Number Paging Properties
Property
Description
#maximumPageSize
The maximum page size in rows.
#firstPageNumber
The number of the first page. The default is 0; however, some systems begin numbering pages at 1.
#pageSizeParameter
The name of the URI parameter that contains the page size.
#pageNumberParameter
When requesting a page of rows, this is the name of the URI parameter to contain the page number.
* Sample input REST file