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:

YAML Mapping (Recommended)

Most API clients can be configured using a YAML mapping file:

# File: auth/make-api-client.map.yml
baseUri: https://api.example.com
headers:
  Authorization:
    $concat:
        - "Bearer "
        - $var: credentials.access_token

In your spec.yml:

auth:
  # ...other auth settings
  makeApiClient:
    implementationType: mapping

Available fields:

• 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 / Typescript code.

It should export a default function that returns a RestApiClient instance.

Example:

// File: auth/make-api-client.js
exports.makeApiClient = function({ credentials }) {
  return {
    baseUrl: 'https://api.example.com',
    headers: {
      'Authorization': `Bearer ${credentials.access_token}`,
      'Content-Type': 'application/json',
      'Accept': 'application/json'
    },
  };
};

In your spec.yml:

auth:
  # ...other auth settings
  makeApiClient:
    implementationType: javascript

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:

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.

API Client Implementation Workflow

• Determine baseUri for the API.
  • Use the shortest baseUri you can. Usually it is just the API domain. The only situations when something else should be in baseUri is when some path prefix is always required in API requests and there cannot be API requests outside of this path.
  • If baseUri requires variables, make sure those variables are in the credentials. Add custom credentials if needed using getCredentialsFromConnectionParameters or getCredentialsFromTokenResponse functions.
• Populate the API request parameters
  • If every API request requires variables that are not in credentials schema by default, add custom credentials implementation.
• Determine if API requires any special response handling that is not addressed by the standard response handlers and add them.