OpenAPI connector configuration

Konstantin Alpashkin

The following configuration parameters can be used to tune the connector’s behavior. You can specify these parameters when creating a new Trino catalog using ADCM or inside the WITH clause, for example:

CREATE CATALOG "openapi-catalog" USING openapi
WITH (
    "spec-location" = ...,
    "base-uri" = ...,
    ...
);
Configuration parameter Description

spec-location

URL or file name containing the OpenAPI specification (JSON/YAML)

base-uri

Base URL of the REST API

authentication.type

Default authentication type to use if it is not specified in the OpenAPI specification. Possible values: none, http, api_key, oauth

authentication.scheme

Authentication schema for the http authentication type. Possible values: basic, bearer

authentication.client-id

OAuth Client ID

authentication.client-secret

OAuth Client secret

authentication.username

Username for the http and oauth authentication types

authentication.password

Password for the http and oauth authentication types

authentication.bearer-token

Bearer token for the http authentication

authentication.api-key-name

API key name

authentication.api-key-value

API key value

max-requests-per-second

Maximum number of HTTP requests per second that can be submitted from a single Trino node

max-splits-per-second

Maximum number of splits per second generated when executing a query

Under the hood the connector uses the Airlift HTTP client, which accepts its own set of properties, for example:

openApi.http-client.log.enabled=true
openApi.http-client.log.path=logs

For more information on tuning the client, see Airlift HTTP client properties.

Array unwrapping

When processing an HTTP response, the connector can unwrap fields with array payloads. For example, assume the connector receives the following HTTP-response:

{
    "transactions_count": 10,
    "items":
    [
        {
            "txn_id": 1,
            "acc_id": 1002,
            "txn_value": 184.0,
            "txn_type": "withdrawal"
        },
        {
            "txn_id": 2,
            "acc_id": 1000,
            "txn_value": 282.95,
            "txn_type": "spb"
        },
        {
            "txn_id": 3,
            "acc_id": 1001,
            "txn_value": 100.00,
            "txn_type": "deposit"
        }
    ]
}

By default, Trino would convert items to a single table row with the array elements:

total_count|                                        items|
-----------+---------------------------------------------+
         10|[{"txn_id": 1, ...}, {"txn_id": 1, ...}, ...]|

To force Trino to "explode" the array and present its contents as a separate table, in your OpenAPI schema, specify the x-unwrap section. For the HTTP response above, the x-unwrap section looks as follows:

 /transactions_batch:
    get:
      summary: Get Transactions Batch
      operationId: get_transactions_batch_transactions_batch_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionBatch'
      x-unwrap:
        resultParam: $response.body#/items (1)
        includeRoot: 'false' (2)
1 The response field holding an array that has to be exploded and displayed as a separate table.
2 Indicates whether to include duplicate fields (transactions_count).

With such x-unwrap configuration, the connector maps the content of the items field to a separate table:

txn_id|acc_id|txn_value|txn_type  |
------+------+---------+----------+
     1|  1002|184.00   |withdrawal|
     2|  1000|282.95   |spb       |
     3|  1001|100.00   |deposit   |

Pagination

The connector supports pagination for the LIMIT pushdown. To enable pagination, in your OpenAPI schema, use x-pagination for the required endpoint:

x-pagination:
  pageParam: "page"
  limitParam: "size"
  resultsPath: "$response.body#/elements"
  totalResultsPath: "$response.body#/totalCount"

Using pagination is not recommended as it may return inconsistent results, especially on large datasets.

Found a mistake? Seleсt text and press Ctrl+Enter to report it