REST API
REST API connectors provide flexible access to external services via HTTP endpoints, enabling integration with a wide variety of web platforms. They support data exchange through RESTful APIs, facilitating dynamic and programmable interactions between systems.
Prerequisites
Before connecting, ensure the following prerequisites are met:
- The API server must be accessible from the iceDQ server.
- Valid credentials to make the API request.
- REST API JDBC version 24.0 or above.
Authentication Mechanisms
The following authentication mechanisms are supported.
- API Key
- Basic
- Bearer Token
- No Auth
- OAuth
Connection Properties
API Key Authentication
Use the following properties to create a valid connection. Properties marked with an asterisk (*) are required.
| Name | Description | Example Values |
|---|---|---|
| Connection Name * | Name that uniquely identifies the connection. | Prod_API_conn |
| Driver * | Driver used to establish the connection. One driver is available by default. | Rest API Custom JDBC |
| Base URL * | The root URL for the REST API to which requests will be sent. | https://api.example.com/v1 |
| Test Endpoint | Endpoint path used to test the API connectivity. | https://jsonplaceholder.typicode.com/posts/1 |
| Response Type * | The type of response expected from the API – either JSON or XML. | JSON |
| Add To * | Where the API key should be added in the request. | Header |
| Type * | The connection type – REST API connection can only be a System Connection. Refer Connections for more details. | System |
| Key * | The header or parameter name where the API key should be placed. | Authorization |
| Value * | The actual API key value used to authenticate the request. | u8w3D~xYtP-5k9LMn.7abc123xyz456 |
Basic Authentication
Use the following properties to create a valid connection. Properties marked with an asterisk (*) are required.
| Name | Description | Example Values |
|---|---|---|
| Connection Name * | Name that uniquely identifies the connection. | Prod_API_conn |
| Driver * | Driver used to establish the connection. One driver is available by default. | Rest API Custom JDBC |
| Base URL * | The root URL for the REST API to which requests will be sent. | https://api.example.com/v1 |
| Test Endpoint | Endpoint path used to test the API connectivity. | https://jsonplaceholder.typicode.com/posts/1 |
| Response Type * | The type of response expected from the API – either JSON or XML. | JSON |
| Tenant ID* | The identifier for the tenant (used in multi-tenant applications, e.g., Azure AD). | 0a8287-789b-4cde-9abc-12345ef67890 |
| Type * | The connection type – REST API connection can only be a System Connection. Refer Connections for more details. | System |
| Username * | Login username with necessary privileges (application or API user). | finance_dw_test_user |
| Password * | Password associated with the specified username. | FinDWTest@2025! |
Bearer Token Authentication
Use the following properties to create a valid connection. Properties marked with an asterisk (*) are required.
| Name | Description | Example Values |
|---|---|---|
| Connection Name * | Name that uniquely identifies the connection. | Prod_API_conn |
| Driver * | Driver used to establish the connection. One driver is available by default. | Rest API Custom JDBC |
| Base URL * | The root URL for the REST API to which requests will be sent. | https://api.example.com/v1 |
| Test Endpoint | Endpoint path used to test the API connectivity. | https://jsonplaceholder.typicode.com/posts/1 |
| Response Type * | The type of response expected from the API – either JSON or XML. | JSON |
| Type * | The connection type – REST API connection can only be a System Connection. Refer Connections for more details. | System |
| Token * | Bearer token used to authorize API requests. This will be sent in the Authorization header. | eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... |
No Auth Authentication
Use the following properties to create a valid connection. Properties marked with an asterisk (*) are required.
| Name | Description | Example Values |
|---|---|---|
| Connection Name * | Name that uniquely identifies the connection. | Prod_API_conn |
| Driver * | Driver used to establish the connection. One driver is available by default. | Rest API Custom JDBC |
| Base URL * | The root URL for the REST API to which requests will be sent. | https://api.example.com/v1 |
| Test Endpoint | Endpoint path used to test the API connectivity. | https://jsonplaceholder.typicode.com/posts/1 |
| Response Type * | The type of response expected from the API – either JSON or XML. | JSON |
| Type * | The connection type – REST API connection can only be a System Connection. Refer Connections for more details. | System |
OAuth Authentication
Use the following properties to create a valid connection. Properties marked with an asterisk (*) are required.
| Name | Description | Example Values |
|---|---|---|
| Connection Name * | Name that uniquely identifies the connection. | Prod_API_conn |
| Driver * | Driver used to establish the connection. One driver is available by default. | Rest API Custom JDBC |
| Base URL * | The root URL for the REST API to which requests will be sent. | https://api.example.com/v1 |
| Test Endpoint | Endpoint path used to test the API connectivity. | https://jsonplaceholder.typicode.com/posts/1 |
| Response Type * | The type of response expected from the API – either JSON or XML. | JSON |
| Add Auth Data To * | Where to include the authentication data in the request. | Request Headers |
| Token Header Prefix * | The prefix added before the token in the header (e.g., Bearer, Token, or none). | Bearer |
| Grant Type * | Grant type used for token-based authentication. Often required in OAuth flows. | client_credentials |
| Callback URL * | The redirect URI where the response is sent during OAuth authentication. | https://192.168.105.43:32222/api/v1/oauth/callback |
| Scope * | The permission scope requested for the token. | openid |
| Auth URL * | The authorization server’s URL where users are redirected to log in. | https://auth.example.com/oauth2/authorize |
| Access Token URL * | The URL used to exchange credentials for an access token. | https://auth.example.com/oauth2/token |
| Refresh Token URL * | The URL used to obtain a new token using a refresh token. | https://auth.example.com/oauth2/refresh |
| Tenant ID * | The identifier for the tenant (used in multi-tenant applications, e.g., Azure AD). | 0a8287-789b-4cde-9abc-12345ef67890 |
| Type * | The connection type – REST API connection can only be a System Connection. Refer Connections for more details. | System |
| Client ID * | The client ID issued by the authorization server. | 0a8257-789b-4cde-9abc-12345ef4742 |
| Client Secret * | The secret key associated with the client ID. Used to authenticate the app with the token server. | u8w3D~xYtP-5k9LMn.7abc123xyz456 |
Custom Properties
The following optional connection properties can be configured based on user requirements.
| Property | Default Value | Possible Values | Description |
|---|---|---|---|
| FirewallPort | 0 | Any integer value | Specifies the port number for the firewall server. |
| FirewallServer | (empty) | Any string value | Specifies the hostname or IP address of the firewall server. |
| FirewallType | NONE | NONE, HTTP, SOCKS4, SOCKS5 | Defines the type of firewall to be used. |
| LoginURL | (empty) | Any valid URL | URL used for login requests when required. |
| ProxyAuthScheme | BASIC | BASIC, DIGEST, NTLM, NONE | Specifies the authentication scheme used for the proxy connection. |
| ProxyAutoDetect | false | true, false | Determines whether the driver automatically detects proxy settings. |
| ProxyPassword | (empty) | Any string value | Password required to authenticate with the proxy server. |
| ProxyPort | 80 | Any integer value | Port number where the proxy server listens for requests. |
| ProxyServer | (empty) | Any string value | Hostname or IP address of the proxy server. |
| ProxyUser | (empty) | Any string value | Username required to authenticate with the proxy server. |
| QueryPassthrough | false | true, false | Determines whether queries are passed directly to the underlying database. |
| Timeout | 60 | Any integer value (seconds) | Maximum time, in seconds, the driver waits for a server response. |