This section provides you with an overview of the steps required to install the Autonomous REST Connector and create a Model file to be used with your connections. The REST model file defines endpoints and table mapping used to generate your relational model. In addition, the Model file is capable of configuring a number of driver behaviors, such as paging, custom authentication, and HTTP response code processing.
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.

To begin accessing data with the driver:

  1. Install the driver:
    1. After downloading the product, unzip the installer files to a temporary directory.
    2. From the installer directory, run the appropriate installer file to start the installer. The installer file takes the following form:

      PROGRESS_DATADIRECT_ODBC_nn_WIN_xx_INSTALL.exe

    3. Follow the prompts to complete installation.
    Note:

    The installer program supports multiple installation methods, including command-line and silent installations. For detailed instructions, refer to the Progress DataDirect for ODBC Drivers Installation Guide.

  2. Before you can use your driver, you must set the PATH environment variable to include the path of the jvm.dll file of your Java™ Virtual Machine (JVM).
  3. 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.


    Hub window for the Autonomous REST Connector Autonomous REST Composer

  4. Select Create Model.
  5. The Create Model window opens.
    Figure 1. The Create Model Window

    The New Project dialog

    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.
  6. The Connection tab of the Autonomous REST Composer opens.
    Figure 2. The Connection tab

    The Connection tab

    Optionally, provide values for the following fields:
    • Host Name: Set this property to specify the host name portion of the HTTP endpoint to which you send requests. For example, a Jira endpoint would take the following form: https://mycompany.atlassian.net.
    • Port Number: Optionally, specify the TCP port of the server that is listening for REST API requests.
  7. 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 for this session. 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.
    Note: Properties for custom authentication are specified in the Model file. You can update the file manually or using the Configuration Manager. For details, see Configuring custom authentication with the Configuration Manager.
  8. Select the Configure Endpoints tab on the side menu.
    Figure 3. The Configure Endpoints tab

    The Edit the 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.
  9. 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 4. Customization Pane

    Customization Pane

  10. 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.
  11. 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.
  12. Optionally, customize your relational schema, including modifying column names, data type mapping, and primary key designation. See Customizing your schema for details.
  13. Optionally, click Test Connect to test your model by executing SQL queries.
  14. 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.

  15. Click Download to generate and download your Model file.
  16. 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. See the following to configure your driver for connection: You can edit your Model file later by opening it by clicking Import Model when starting the Autonomous REST Composer.
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.