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.