> ## Documentation Index
> Fetch the complete documentation index at: https://docs.membrane.agency/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```yaml theme={null}
# 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:

```yaml theme={null}
# 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:

```yaml theme={null}
# 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](/docs/references/formulas) 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.