Progress DataDirect® Autonomous REST Connector for ODBC Quick Start for Linux
Release 8.0.0
Copyright
© 2019 Progress Software Corporation and/or one of its subsidiaries or affiliates. All rights reserved. These materials and all Progress® software products are copyrighted and all rights are reserved by Progress Software Corporation. The information in these materials is subject to change without notice, and Progress Software Corporation assumes no responsibility for any errors that may appear therein. The references in these materials to specific platforms supported are subject to change. Corticon, DataDirect (and design), DataDirect Cloud, DataDirect Connect, DataDirect Connect64, DataDirect XML Converters, DataDirect XQuery, DataRPM, Deliver More Than Expected, Icenium, Kendo UI, Kinvey, NativeScript, OpenEdge, Powered by Progress, Progress, Progress Software Developers Network, Rollbase, SequeLink, Sitefinity (and Design), Sitefinity, SpeedScript, Stylus Studio, TeamPulse, Telerik, Telerik (and Design), Test Studio, and WebSpeed are registered trademarks of Progress Software Corporation or one of its affiliates or subsidiaries in the U.S. and/or other countries. Analytics360, AppServer, BusinessEdge, DataDirect Autonomous REST Connector, DataDirect Spy, SupportLink, DevCraft, Fiddler, JustAssembly, JustDecompile, JustMock, NativeChat, NativeScript Sidekick, OpenAccess, ProDataSet, Progress Results, Progress Software, ProVision, PSE Pro, SmartBrowser, SmartComponent, SmartDataBrowser, SmartDataObjects, SmartDataView, SmartDialog, SmartFolder, SmartFrame, SmartObjects, SmartPanel, SmartQuery, SmartViewer, SmartWindow, and WebClient are trademarks or service marks of Progress Software Corporation and/or its subsidiaries or affiliates in the U.S. and other countries. Java is a registered trademark of Oracle and/or its affiliates. Any other marks contained herein may be trademarks of their respective owners.
Updated: 2019/03/12
Progress DataDirect Autonomous REST Connector for ODBC: Quick Start for Linux: Version 8.0.0 3 Copyright
4 Progress DataDirect Autonomous REST Connector for ODBC: Quick Start for Linux: Version 8.0.0 Quick Start: Progress DataDirect Autonomous REST Connector for ODBC on Linux
The Progress DataDirect Autonomous REST Connector for ODBC is a driver that supports SQL read-only access to REST API data sources. This quick start guide provides the basic information necessary to install, configure, and connect to REST API data sources on Linux platforms. For the complete documentation library, refer to: Progress DataDirect Documentation Library
Note: OEM CUSTOMERS: Refer to the Progress DataDirect for ODBC Drivers Distribution Guide for information on installing, branding, unlocking, and distributing your branded drivers.
This quick start covers the following topics:
• Before You Start on page 5 • Requirements and Support on page 6 • Downloading the Driver on page 6 • Installing the ODBC Driver on Linux on page 7 • Environment Configuration on page 9 • Creating an Input REST File on page 9 • Setting the Library Path Environment Variable on page 16 • Configuring a Data Source on page 17 • Configuring Authentication on page 18 • Testing the Connection on page 20 • Troubleshooting Setup/Connection Issues on page 20 • Additional Resources on page 21
Before You Start
Before you get started, you need the following:
• Appropriate user permissions to modify your environment and to read, write, and execute various files in the DataDirect for ODBC installation directory. • Connection information: • Authentication Method: The method your endpoints use to authenticate users. The Autonomous REST Connector supports basic, token based (HTTP Header and URL based), and no authentication.
Progress DataDirect Autonomous REST Connector for ODBC: Quick Start for Linux: Version 8.0.0 5 Chapter 1: Quick Start: Progress DataDirect Autonomous REST Connector for ODBC on Linux
• User Name and Password: If required by your authentication method, the user ID and password used to access your data source. • URL Parameter: For URL-based authentication, the name of the URL parameter used to pass the security token. • HTTP Header Name: For basic and HTTP header authentication methods, the name of your HTTP header used for authentication, if it differs from the default value of Authorization. • HTTP Endpoints: A list of the HTTP endpoints that you want to map to the relational view. Note that additional endpoints can be added during later sessions. • (Optional) Location to store internal driver files: The path you want the driver to use to generate and store internal configuration files. This location is not used when the driver uses memory to store mapping information for the session (the default). When configured to generate internal files by setting the CreateMap option to either 1 (ForceNew) or 2 (NotExist), the driver will attempt to use the following directory by default: ~/progress/datadirect/AutoREST_Schema/
• For licensed installations, you will also need the following information that was provided by Progress DataDirect:
• Control Number (IPE Key) • Serial Number
Requirements and Support
Driver/Client Software Requirements:
• Java Virtual Machine (JVM) that is Java SE 8 or higher, including Oracle JDK, OpenJDK, and IBM SDK (Java) distributions.
Supported Data Sources: The driver supports a variety of REST API deployments that employ:
• Payloads expressed in the JSON format. • Basic, token (URL or header-based), or no authentication. For the latest versions supported by the driver, refer to the supported configurations page on the Progress DataDirect Web site: https://www.progress.com/supported-configurations/datadirect.
Downloading the Driver
To download the ODBC Autonomous REST Connector:
1. Visit the Progress DataDirect download site at: http://forms.progress.com/forms/driverdownload
2. Complete the questionnaire. To download the driver, provide the following values:
6 Progress DataDirect Autonomous REST Connector for ODBC: Quick Start for Linux: Version 8.0.0 Installing the ODBC Driver on Linux
• When prompted for your data source, select Autonomous REST API. • When prompted for an interface, select ODBC. • When prompted for your OS and architecture, select the platform and bitness used by your application.
3. Fill-in the registration form with your contact information. 4. Review the End User License Agreement. If you agree, check the corresponding box; then, click Download.
The installer program has been downloaded. See "Installing the ODBC Driver on Linux" for instructions on installing the driver.
See also Installing the ODBC Driver on Linux on page 7
Installing the ODBC Driver on Linux
This section provides instructions for installing your downloaded files from a command-line interface. Depending on your environment, you can also install using GUI or silent installation options. Refer to the Progress DataDirect for ODBC Drivers Installation Guide for complete installation instructions.
1. Download the appropriate product file from the Web site into a temporary directory, for example, /tmp. 2. Switch the temporary directory; then, choose one of the following: 3. Extract the contents of the product file. Enter: tar -xvzf product_filename.tgz where product_filename is the name of the tarred product file name. The untarred files appear in the temporary directory.
4. Run the installer program by switching to the temporary directory that contains the untarred installer files and entering: ./installer_filename.bin –i console where:
installer_filename
is the full name of the installer's binary file you untarred in Step 3 on page 7 .
5. The Introduction step appears. Press ENTER. 6. The product license agreement appears. Press SPACEBAR to page to the end of the agreement. At the end, you are asked to accept the agreement:
• Enter Y to accept the license agreement and continue with the installation. • Enter N to abort the installation.
Note: You can exit the installer program at any time by typing quit or return to the previous step by typing previous.
Progress DataDirect Autonomous REST Connector for ODBC: Quick Start for Linux: Version 8.0.0 7 Chapter 1: Quick Start: Progress DataDirect Autonomous REST Connector for ODBC on Linux
7. You are prompted to enter the absolute path to the installation directory. The default is: For 32-bit installations: opt/Progress/DataDirect/ODBC_nn_32bit For 64-bit installations: opt/Progress/DataDirect/ODBC_nn_64bit If you do not have /opt directory permissions, the installer program installs the drivers to your home directory by default. For example, the directory for 32-bit installation would be: /home_directory/Progress/DataDirect/ODBC_nn_32bit where
nn
is the product version number. For example, this value is 80 for the 8.0 version of the product.
home_directory
is the home directory for the user who is installing the product.
8. You are prompted for the type of installation:
• If you are installing an evaluation copy of the product (expires in 15 days), enter 1. Then, press Enter to confirm the evaluation information. Skip to Step 11 on page 8. • If you are installing a OEM or licensed copy of the product, enter 2. Proceed to the next step.
Note: If you were issued multiple product keys, you can type them sequentially, separating the keys with a space. For example: xxxxkey1 xxxxkey2 xxxxkey3
9. You are prompted to enter the control that was provided by Progress DataDirect. Type the control number, including dashes, and then press ENTER. Proceed to the next step. 10. The installer prompts you for product registration information. Enter your name, your company name, and the serial number provided by Progress DataDirect; then, press ENTER. 11. The Pre-Installation Summary step provides the opportunity for you to review the information you have entered, and you are prompted to accept or change the information:
• Press ENTER to accept the information and begin the installation. • To change the information, type back and then press ENTER. You are prompted for the information again. • If you are installing with a licensed OEM IPE key, you are prompted for branding information. Please refer to the Progress DataDirect for ODBC Drivers Distribution Guide.
12. After completion of the installation, a message appears indicating that you have installed the software successfully. Press ENTER to close the installer.
After installation, proceed to "Environment Configuration."
8 Progress DataDirect Autonomous REST Connector for ODBC: Quick Start for Linux: Version 8.0.0 Environment Configuration
Environment Configuration
After installing your driver, your first step in setting up and configuring the driver is to configure your environment variables. The following procedures require that you have the appropriate permissions to modify your environment and to read, write, and execute various files. You must log in as a user with full r/w/x permissions recursively on the entire product installation directory. To configure the environment:
1. Check your permissions. You must log in as a user with full r/w/x permissions recursively on the entire product installation directory. 2. From your login shell, determine which shell you are running by executing: echo $SHELL
3. Run one of the following product setup scripts from the installation directory to set variables: odbc.sh or odbc.csh. For Korn, Bourne, and equivalent shells, execute odbc.sh. For a C shell, execute odbc.csh. After running the setup script, execute: env to verify that the installation_directory/lib directory has been added to your shared library path.
4. Set the ODBCINI environment variable. The variable must point to the path from the root directory to the system information file where your data source resides. The system information file can have any name, but the product is installed with a default file called odbc.ini in the product installation directory. For example, if you use an installation directory of /opt/odbc and the default system information file, from the Korn or Bourne shell, you would enter: ODBCINI=/opt/odbc/odbc.ini; export ODBCINI From the C shell, you would enter: setenv ODBCINI /opt/odbc/odbc.ini
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 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.
Progress DataDirect Autonomous REST Connector for ODBC: Quick Start for Linux: Version 8.0.0 9 Chapter 1: Quick Start: Progress DataDirect Autonomous REST Connector for ODBC on Linux
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:
{ "
Specifying Endpoints for GET Request with Unparameterized Paths To specify endpoints for unparameterized GET requests, use the following format:
"
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://example.com. You can omit this value by specifying the host name using the Host Name (HostName) option.
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://example.com/countries/",
10 Progress DataDirect Autonomous REST Connector for ODBC: Quick Start for Linux: Version 8.0.0 Creating an Input REST File
Specifying Endpoints for GET Request with Parameterized Paths To specify parameterized GET requests, use the following format:
"
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://example.com. You can omit this value by specifying the host name using the Host Name (HostName) option.
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.
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.
"states":"http://example.com/states/get/{countryCode:USA}/all",
Progress DataDirect Autonomous REST Connector for ODBC: Quick Start for Linux: Version 8.0.0 11 Chapter 1: Quick Start: Progress DataDirect Autonomous REST Connector for ODBC on Linux
Specifying Endpoints for GET Requests with Query Parameters Use the following format to specify endpoints for GET requests with argument parameters. Multiple argument parameters within the same endpoint are separated by an ampersand (&).
"
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://example.com. You can omit this value by specifying the host name using the User Name (UserName) option.
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.example.com/times/query?interval=5min&symbol=USA&function=TIME_SERIES_WEEKLY",
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:
"table_name":{ "#path": "
12 Progress DataDirect Autonomous REST Connector for ODBC: Quick Start for Linux: Version 8.0.0 Creating an Input REST File
table_name
is the name of the relational table to which the driver maps the endpoint. For example, people.
host_name
(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 option.
endpoint_path
is the path component of the URL endpoint. For example, times.
header
is the HTTP header component of the header=value pair used for filtering the request. For example, X-Subway-Payment. When overriding the Accept header, this value is Accept.
value
is the value argument for the HTTP header used for filtering the request or, if overriding the default Accept header, the value of the Accept header for the endpoint. For example, token.
For example, the following demonstrates an entry for a GET request that defines custom HTTP headers.
"people":{ "#path": "http://example.com/people", "#headers":{ "Accept":"application/calendar+json" "X-Subway-Payment":"token", "X-Laundry-Service":"dryclean", "X-Favorite-Food":"pizza" } },
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 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": "
table_name
is the name of the relational table to which the driver maps the endpoint. For example, countries2.
Progress DataDirect Autonomous REST Connector for ODBC: Quick Start for Linux: Version 8.0.0 13 Chapter 1: Quick Start: Progress DataDirect Autonomous REST Connector for ODBC on Linux
host_name
(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.
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://example.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": "
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://example.com. You can omit this value by specifying the host name using the Host Name (HostName) option.
14 Progress DataDirect Autonomous REST Connector for ODBC: Quick Start for Linux: Version 8.0.0 Creating an Input REST File
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.
Progress DataDirect Autonomous REST Connector for ODBC: Quick Start for Linux: Version 8.0.0 15 Chapter 1: Quick Start: Progress DataDirect Autonomous REST Connector for ODBC on Linux
Sample Input REST File
The following is a sample input REST file that demonstrates GET requests, POST requests, and a request configured for paging:
{ // a simple GET request without parameters to sample: "countries":"http://example.com/country",
// A GET request with a parameter in the path: "states":"http://example.com/states/get/{countryCode:USA}/all",
// A GET request with parameters as arguments
"timeseries":"https://www.example.com/times/query?interval=5min&symbol=USA&function=TIME_WEEKLY",
// A GET request with parameters as arguments "timeseries":"https://www.example.com/times/query?interval=5min&symbol=USA&function=TIME_WEEKLY",
// A GET request with custom HTTP headers "people":{ "#path": "http://example.com/people", "#headers":{ "Accept":"application/calendar+json" "X-Subway-Payment":"token", "X-Laundry-Service":"dryclean", "X-Favorite-Food":"pizza" } },
// A POST with parameters in the body "countries2": { "#path": "http://example.com/country", "#post": { "start_date":"2018-08-31", "end_date":"2018-09-01", "departments":"[engineering,marketing,sales]", "tags":"[blue,green,red]" } },
// A GET with paging configured "products": { "#path": "http://example.com/products", "#maximumPageSize":1000, "#firstRowNumber":1, "#pageSizeParameter":"maxResults", "#rowOffsetParameter":"startAt" }, }
Setting the Library Path Environment Variable
Before you can use the Autonomous REST Connector, you must set the library path environment variable for your Linux operating system to include the directory containing your JVM’s libjvm.so [sl | a] file, and that directory’s parent directory. For 32-bit and 64-bit drivers, the Library Path Environment Variable on Linux is LD_LIBRARY_PATH.
16 Progress DataDirect Autonomous REST Connector for ODBC: Quick Start for Linux: Version 8.0.0 Configuring a Data Source
Configuring a Data Source
The default odbc.ini file installed in the installation directory is a template in which you create data source definitions. You enter your site-specific database connection information using a text editor. Each data source definition must include the keyword Driver=, which is the full path to the driver. The following examples show the minimum connection string options that must be set to complete a test connection, where xx represents iv for 32-bit or dd for 64-bit drivers, and yy represents the extension. The values for the options are samples and are not necessarily the ones you would use. For sessions using an input REST file (sessions with multiple endpoints, POST requests, paging, or custom headers) with no authentication:
[ODBC Data Sources] AutoREST=DataDirect 8.0 Autonomous REST Connector
[AutoREST] Driver=ODBCHOME/lib/xxautorestyy.zz Config=C:/path/to/myrest.rest
For sessions using the Sample option with no authentication:
[ODBC Data Sources] AutoREST=DataDirect 8.0 Autonomous REST Connector
[AutoREST] Driver=ODBCHOME/lib/xxautorestyy.zz Sample=https://example.com/countries/
Table 3: Essential Connection Options
Connection Option Attribute Characteristic
Required Options
Config Specifies the name and location of the input REST file that contains the list of endpoints to sample and paging configuration information. For example, C:/path/to/mysite.rest. For more information on information on the REST file, see "Creating a REST File for Multiple End Points."
Note: The Config property determines whether the driver uses an input REST file for the session. If no value is provided, an endpoint must be provided using the Sample property.
Sample Specifies the endpoint that the driver connects to and samples. This option allows you to configure the driver to issue GET requests to a single endpoint without creating an input REST file.
Note: This option is required when not using an input REST file.
Progress DataDirect Autonomous REST Connector for ODBC: Quick Start for Linux: Version 8.0.0 17 Chapter 1: Quick Start: Progress DataDirect Autonomous REST Connector for ODBC on Linux
Connection Option Attribute Characteristic
Optional Options
Authentication-related options The preceding examples demonstrate connecting to an endpoint using no authentication. If your endpoint requires authentication, see Configuring Authentication on page 18 for a description of related options and examples.
CreateMap Determines whether the driver creates the internal files required for a relational map of the native data when establishing a connection. If set to 0 (No), the driver uses the current REST file, internal files, and relational map in the location specified by the Schema Map option. If one does not exist, the connection fails. If set to 1 (ForceNew), the driver deletes the current REST file, internal configuration files, and relational map in the location specified by the Schema Map option and creates a new set at the same location. If set to 2 (NotExist), the driver uses the current REST file, internal files, and relational map in the location specified by the Schema Map option. If the files do not exist, the driver creates them. If set 3 (Session), the driver uses memory to store the internal configuration information and relational map of native data. A REST file is not created when this value is specified. After the session, the view is discarded. Default: 3 (Session)
HostName Specifies the host name portion of the HTTP endpoint to which you send requests. Specify this value if you want to define endpoints without storing the host name component in the REST file.
SchemaMap Specifies the directory where internal files and the relational map of native data data are written. The driver looks for this location when connecting to an endpoint. If these files do not exist, the driver creates them. Windows default: application_data_folder\Local\Progress\DataDirect\AutoREST_Schema\ Linux default: ~/progress/datadirect/AutoREST_Schema/
Configuring Authentication
The driver supports the authentication methods described in this section. By default, the driver is configured to use no authentication (AuthenticationMethod=None).
Basic Authentication Basic authentication uses user IDs, passwords, and HTTP headers to authenticate.
18 Progress DataDirect Autonomous REST Connector for ODBC: Quick Start for Linux: Version 8.0.0 Configuring Authentication
• Configure the Config or Sample connection option attributes. • Set the AuthenticationMethod option to Basic. • (Optional) Set the AuthHeader option to specify the name of the HTTP header used for authentication. The default is Authorization. • Set the LogonID option to specify your logon ID. • Set the Password option to specify your password. The following examples demonstrate a session using a REST file with basic authentication enabled and AuthHeader set to the default:
[ODBC Data Sources] AutoREST=DataDirect 8.0 Autonomous REST Connector
[AutoREST] Driver=ODBCHOME/lib/ivautorestxx.so AuthenticationMethod=Basic Config=C:\path\to\myrest.rest LogonID=jsmith Password=secret
HTTP Header Authentication HTTP Header Authentication passes security tokens via the HTTP headers to authenticate. In some scenarios, the REST services may also authenticate the user ID. To configure the driver to use HTTP header authentication: • Configure the Config or Sample connection option attributes. • Set the AuthenticationMethod option to HttpHeader. • (Optional) Set the AuthHeader option to specify the name of the HTTP header used for authentication. The default is Authorization. • Set the SecurityToken option to specify the security token required to make a connection to your endpoint. For example, XaBARTsLZReM. The following examples demonstrates a session using a REST file with HTTP header authentication enabled and AuthHeader is set to the default.
[ODBC Data Sources] AutoREST=DataDirect 8.0 Autonomous REST Connector
[AutoREST] Driver=ODBCHOME/lib/ivautorestxx.so Description=My Autonomous REST Data Source AuthenticationMethod=HttpHeader Config=C:\path\to\myrest.rest SecurityToken=XaBARTsLZReM
URL Parameter Authentication URL Parameter Authentication authenticates by passing security tokens using URLs. In some scenarios, the REST services may also authenticate the user ID. To configure the driver to use HTTP header authentication: • Configure the Config or Sample options. • Set the AuthenticationMethod option to UrlParameter. • Set the AuthParam option to specify the name of the URL parameter used to pass the security token. For example, apikey.
Progress DataDirect Autonomous REST Connector for ODBC: Quick Start for Linux: Version 8.0.0 19 Chapter 1: Quick Start: Progress DataDirect Autonomous REST Connector for ODBC on Linux
• Set the SecurityToken option to specify the security token required to make a connection to your endpoint. For example, XaBARTsLZReM. The following examples demonstrates a session using a REST file with URL parameter authentication enabled.
[ODBC Data Sources] AutoREST=DataDirect 8.0 Autonomous REST Connector
[AutoREST] Driver=ODBCHOME/lib/ivautorestxx.so; Description=My Autonomous REST Data Source AuthenticationMethod=UrlParameter AuthParam=apikey Config=C:\path\to\myrest.rest SecurityToken=XaBARTsLZReM
Testing the Connection
The driver installation includes an ODBC application called example that can be used to connect to a data source and execute SQL. The application is located in the installation_directory/samples/example directory. To run the program after setting up a data source in the odbc.ini, enter example and follow the prompts to enter your data source name, user name, and password. If successful, a SQL> prompt appears and you can type in SQL statements such as SELECT * FROM INFORMATON_SCHEMA.SYSTEM_TABLES. If example is unable to connect, the appropriate error message is returned.
Troubleshooting Setup/Connection Issues
This section describes common setup/connection issues you may encounter while trying to establish a database connection with the driver as well as some potential reasons for these issues. If you are experiencing a problem not described in this section, comprehensive troubleshooting resources are available in the "Troubleshooting" section of the user's guide and reference for your driver. In addition, Progress DataDirect offers a variety of options to meet your technical support needs. See Contacting Technical Support on page 21 for details.
Common Setup/Connection Issues
You are experiencing a setup/connection issue if you are encountering an error or hang while you are trying to make a database connection with the ODBC driver or are trying to configure the ODBC driver. Some common errors that are returned by the ODBC driver if you are experiencing a setup/connection issue include: • Specified driver could not be loaded. • Data source name not found and no default driver specified. • Unable to connect to destination. • Invalid username/password; logon denied.
20 Progress DataDirect Autonomous REST Connector for ODBC: Quick Start for Linux: Version 8.0.0 Additional Resources
Troubleshooting the Issue
Some common reasons that setup/connection issues occur are:
• The database and/or listener are not started. • The ODBCINI environment variable is not set correctly for the ODBC drivers on Linux. • The ODBC driver’s connection attributes are not set correctly in the system information file on Linux. See "Configuring a Data Source" for more information. For example, the host name or port number are not correctly configured.
See also Configuring a Data Source on page 17
Additional Resources
In addition to this quick start, the following resources enable you to take full advantage of the features and support offered for your driver. • Product Documentation Library contains a comprehensive set of product documentation, including the following guides: • Progress DataDirect for ODBC Drivers Installation Guide details requirements and procedures for installing the product. • Progress DataDirect Autonomous REST Connector for ODBC User's Guide and Reference guides you through using and configuring the driver, provides detailed reference information, and explains the tools used to troubleshoot common problems.
• Progress Support Knowledgebase provides answers to questions, access to technical documentation, release notes, product alerts and other support information. • Progress Community allows you to contribute, share, and network with other Progress users and employees. • Technical Support provides technical support services, including maintenance services and opening a support case.
Contacting Technical Support
Progress DataDirect offers a variety of options to meet your support needs. Please visit our Web site for more details and for contact information: https://www.progress.com/support The Progress DataDirect Web site provides the latest support information through our global service network. The SupportLink program provides access to support contact details, tools, patches, and valuable information, including a list of FAQs for each product. In addition, you can search our Knowledgebase for technical bulletins and other information. When you contact us for assistance, please provide the following information:
Progress DataDirect Autonomous REST Connector for ODBC: Quick Start for Linux: Version 8.0.0 21 Chapter 1: Quick Start: Progress DataDirect Autonomous REST Connector for ODBC on Linux
• Your number or the serial number that corresponds to the product for which you are seeking support, or a case number if you have been provided one for your issue. If you do not have a SupportLink contract, the SupportLink representative assisting you will connect you with our Sales team. • Your name, phone number, email address, and organization. For a first-time call, you may be asked for full information, including location. • The Progress DataDirect product and the version that you are using. • The type and version of the operating system where you have installed your product. • Any database, database version, third-party software, or other environment information required to understand the problem. • A brief description of the problem, including, but not limited to, any error messages you have received, what steps you followed prior to the initial occurrence of the problem, any trace logs capturing the issue, and so on. Depending on the complexity of the problem, you may be asked to submit an example or reproducible application so that the issue can be re-created. • A description of what you have attempted to resolve the issue. If you have researched your issue on Web search engines, our Knowledgebase, or have tested additional configurations, applications, or other vendor products, you will want to carefully note everything you have already attempted. • A simple assessment of how the severity of the issue is impacting your organization.
22 Progress DataDirect Autonomous REST Connector for ODBC: Quick Start for Linux: Version 8.0.0