Skip to main content
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: 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.