Make API Client

The makeApiClient method configures how your connector will make API requests to the external service.

This method is required for all authentication types and creates a REST API client with the appropriate authentication headers, base URL, and other configuration settings.

Implementation Examples

You can implement this method in two ways:

Mapping (Recommended)

Most API clients can be configured using a mapping:

# Connector definition: Simple Bearer token authentication
makeApiClient:
  type: mapping
  mapping:
    baseUri: https://api.example.com
    headers:
      Authorization:
        $concat:
          - 'Bearer '
          - $var: credentials.access_token

Available fields in the mapping:

• baseUri - base URL for all API requests.
• headers - default headers to include in all requests.
• query - default query parameters to include in all requests.
• auth - parameters for basic authentication:
  • username
  • password
• responseHandlers - list of response handlers to apply to all responses (see below).

JavaScript Implementation

For more complex API clients, you can use JavaScript code.

The function should return a RestApiClient configuration object.

Example:

# Connector definition: Dynamic API client with custom headers
makeApiClient:
  type: javascript
  code: |
    export default function makeApiClient({ credentials }) {
      return {
        baseUri: "https://api.example.com",
        headers: {
          Authorization: `Bearer ${credentials.access_token}`,
          "Content-Type": "application/json",
          Accept: "application/json",
        },
      }
    }

Response Handlers

By default, API client will handle responses using the following logic:

• status >= 200 && status < 300 - return response.
• status == 401 - throw ACCESS_TOKEN_EXPIRED error that will trigger an attempt to refresh credentials (if possible).
• status == 429 - throw RATE_LIMIT_EXCEEDED error that will lead to retrying the request with exponential backoff until timeout is reached.

You can augment or override this logic by providing a list of response handlers. Each handler consists of:

• A filter that checks response status, headers, or data and returns true if the handler should be applied.
• A flag that indicates whether it is a successful request or an error should be thrown.
• Data that will be returned if request is successful (by default, the response body will be returned).
• Error that will be thrown if the request is not successful.

Example:

# Connector definition: Handle custom error response indicating expired token
makeApiClient:
  type: mapping
  mapping:
    baseUri: https://api.example.com
    headers:
      Authorization:
        $concat:
          - 'Bearer '
          - $var: credentials.access_token
    responseHandlers:
      - match:
          $eval:
            $var: response.data.category
          is: EXPIRED_AUTHENTICATION
        isSuccess: false
        error:
          message: Access token has expired
          key: access_token_expired
          data:
            $var: response.data

Handler configuration fields:

• match - Formula that returns true or false based on the response.
• isSuccess - flag that indicates whether it is a successful request or an error should be thrown.
• error - error that will be thrown if the request is not successful. Error fields:
  • message - error message.
  • key - error key (one of the available keys of ConnectionError type)
  • data - additional data to include in the error.