The Configuration Manager includes a REST management tool that allows you to
generate and edit Model files. The primary purpose of the Model file is to define
endpoint and table mapping, but it is also capable of configuring a number of driver
behaviors, such as paging and pushdowns. After generating the Model file, you can share
it among multiple installations of the driver.
To generate your Model file:
Open the Autonomous REST Composer by using one of the following
methods:
Select the Autonomous REST Composer
(ODBC) icon from your desktop or the Windows Start
menu.
From a command line, navigate to the directory containing the
autorest.jar file and execute the following
command:
java -jar autorest.jar --odbcdesign
By
default, the autorest.jar file is stored in the
following directory:
install_dir\Progress\DataDirect\ODBC\java\lib\.
The Autonomous REST Composer opens in your default web browser.
Figure 1. Hub window for Autonomous REST Connector
Select Create a Model.
Note: If you
are accessing a publicly available data source, refer to the library of
Model files for your data source. These Model files contain fully defined
requests and pagination setting, allowing you to connect after providing
your authentication credentials. See Getting started using prebuilt Model files (Windows) for
details.
The Create Model window opens.
Figure 2. The Create Model Window
Complete the following fields to create a new project; then, click
OK:
Model Name: The name of your Model file to be
created.
Model Description: An optional
description of your Model. Note that this description will be stored in
clear text in the Model file.
Base URL: The host name portion
of your REST endpoints.
The Configuration Manager opens to the Connection tab.
Figure 3. The Connection tab
Select the Authentication Method used by your endpoints; then, provide
values for the appropriate fields:
In the Configure Authentication Method(s) field, select the method(s)
used by your service.
In the Authentication Method drop-down, select the method you want to
configure. The fields associated with the method you select are exposed.
In the exposed fields, provide values for the applicable fields. Note
that not all of the fields exposed are required for all services.
See Authentication for a full description of these methods.
Note: Authentication properties specified through the
Configuration Manager are not persisted in the Model file. To share
authentication settings among all connections using the file, you must
manually update the Model file. See OAuth 2.0 authentication for
details.
Select the Configure Endpoints tab on the side
menu.
Figure 4. The Configure Endpoints tab
Provide the minimum required information for an
endpoint to which you want to issue requests:
From the Endpoint
drop-down menu, select the type of request to issue against your
endpoint.
In the Endpoint field, type the
path portion of your endpoint after the base URL. Note that the value
must be URL-encoded using valid syntax. For example, spaces in an
endpoint are replaced with %20. See "URL-encoded
values" for details.
In the Table Name
field, type the name of the relational table to which you want the
endpoint to map.
Optionally, further define your endpoint using the customization pane on
the right. For example, specifying query parameters, parameterized paths, and
POST request bodies. For detailed descriptions of defining different types of
endpoints, see Sampling REST endpoints.
Figure 5. Customization Pane
Click Send. The driver sends the
REST request and generates a relational view of the data based on the response.
To add additional endpoints, click + in
the request pane on the left.
Optionally, in the Pagination section
of the customization pane, select the paging method to be used for your Model;
then, provide values for the applicable paging parameters. For a description of
these parameters, see Paging.
Optionally, customize your relational schema, including modifying column
names, data type mapping, and primary key designation. See Customizing your schema for details.
Optionally, click Test Connect to test your model by executing SQL
queries.
Optionally, you can review the status of your endpoints by querying the
SYSTEM_SAMPLING_STATUS system table. For example:
SELECT * FROM INFORMATION_SCHEMA.SYSTEM_SAMPLING_STATUS
This
will allow you to verify that your endpoints have been successfully sampled
by the driver and diagnose any issues, should they occur. See Reviewing the status of your endpoints for details.
Click Download to generate and
download your Model file.
Move your Model file to a location to be used by the driver. When
configuring your connection string or data source, you will also need to specify
this location using the REST Config File (Config) connection option.
After creating your Model file, you are ready to configure and connect. You
can edit your Model file later by opening it from the Create
New Project window when starting the Configuration Manager.
Note: The Model file generated by
the Configuration Manager supports most of the request types and functionality
typically used to access a service. However, the driver supports additional features
and functionality that are not currently available through the file generated by the
Configuration Manager. If you need to configure features or functionality not
supported through the Configuration Manager, you can manually edit your generated
file using a text editor. See "Model file syntax" for details.
