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 does any of the following:
Accesses multiple endpoints
Issues POST requests
Accesses endpoints that require paging
Accesses endpoints that use custom HTTP-headers
If your session does not require a REST file, you can specify your endpoint, for GET requests, using the REST Sample Path (Sample) option instead. For sessions that use a REST file, you will need to create a REST file and specify its location using the REST Config File (Config) option.
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:
is the name of the relational table to which the driver maps the endpoint. For example, states.
(optional) is the protocol and host name components of the URL endpoint. For example, http://example.com. You can omit this value by specifying the host name using the Host Name (HostName) option.
is the path component of the URL endpoint. For example, states.
is the parameter identifier used for filtering the request. For example, countryCode.
is the parameter value used for filtering the request. For example, USA.
Note: When generating the relational map, the driver maps parameter identifiers specified in GET requests as columns, while the corresponding parameter values become the default values for each row within these columns. This allows data to be filtered by these parameters using the Where clause.
For example, the following demonstrates a GET request that will map to the states table.
Specifying Endpoints for GET Requests with Custom HTTP Headers
Some endpoints employ custom HTTP headers to filter data returned by a GET request. This type of filtering is typically used to create multiple unique reports/tables from the same endpoint. To use custom headers, you must define the request in the input REST file. The REST file entry is comprised of a path and header object. The path object contains the URL endpoint used in requests, while the header object defines the headers and provides value arguments used to filter the request.
In addition to filtering requests, the header object can be used to specify a value for the Accept header if the default, application/json, is not accepted by the endpoint. This scenario sometimes occurs when accessing a vendor endpoint that uses a proprietary Accept header.
An entry for a GET request using custom HTTP headers takes the following form:
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 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:
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: