# Connections

## Implementing Connections

**Connections** enable you to connect to third-party tools and services in your custom Book. To implement a connection, define a Python function in your Book class and decorate it with the [**@connect**](https://docs.kognitos.com/legacy/legacy-experience/books/custom-books/api-reference/decorators/connect-decorator) decorator. This decorated function serves as the connection handler and defines the syntax for writing a [connection command](https://docs.kognitos.com/legacy/legacy-experience/books/connections).

{% hint style="warning" %}
**Note:** Implementing an **OAuth** connection in a custom BDK Book is not supported at this time.
{% endhint %}

### Multiple Connections

You can define multiple connections within a Book, each with its own handler method. Use the `noun_phrase` keyword argument in the [**@connect**](https://docs.kognitos.com/legacy/legacy-experience/books/custom-books/api-reference/decorators/connect-decorator) decorator to assign a unique label to each connection and differentiate between authentication methods.

### Method Docstrings

In your connection method docstring, include the following sections in addition to a brief summary:

#### 1. Arguments

Specify the Python function's parameters.

#### 2. Labels

Define labels for the connection arguments (e.g., API key, credentials) that will be used in your [connection command](https://docs.kognitos.com/legacy/legacy-experience/books/connections). Labels correspond to parameters in your function's definition.

When a label is provided in the docstring, the lowercase form is used in a connection command. When *not* provided, the label will be inferred from the Python variable name.

**Example**

```python
@connect(noun_phrase="api keys")
def connect(self, api_key: str):
    """
    Authenticate to Open Weather API using the specified API key. You can obtain your own API key by visiting
    Open Weather's website at https://openweathermap.org/appid.

    Arguments:
        api_key: The API key to be used for connecting

    Labels:
        api_key: API Key
    """

    api_key = os.getenv("API_KEY", api_key)
    test_url = f"{self._base_url}?appid={api_key}&q=London"
    response = requests.get(test_url, timeout=self._timeout)
    if response.status_code == 401:
        response_data = response.json()
        if "Invalid API key" in response_data.get("message", ""):
            raise ValueError("Invalid API key")

    self._api_key = api_key
```

In this example, `API Key` is the label for the `api_key` connection argument. The lowercase version of the label is used in a connection command (`api key`):

```
connect openweather via some api keys method with
    the api key is "aBcDefg1234"
```

**Additional Examples**

1. `api_key: ApI kEy`

In this example, the connection command uses the lowercase form of `ApI kEy`:

```
connect openweather via some api keys method with
    the api key is "aBcDefg1234"
```

2. `api_key: aPi_KeY`

In this example, the connection command uses the lowercase version of `aPi_KeY`:

```
connect openweather via some api keys method with
    the api_key is "aBcDefg1234"
```

3. No Label

If a label is not provided in the docstring, it is inferred from the Python variable name, `api_key`:

```
connect openweather via some api keys method with
    the api key is "aBcDefg1234"
```