# Connecting to External Services

As of release 102, Limio has introduced a new method for creating simple generic integrations that can be utilised in custom components through our backend. This approach enables access to protected resources and avoids CORS issues. This is useful if you want to check some data against a third-party API such as a checkout field against an external service.

### Features

* Supports appending specific values to query strings in GET requests
* Allows adding parameters to bodies for POST requests
* Currently supports query string and body parameters

### Configuring an Integration

1. Navigate to Settings -> Integration and select "Generic"
2. A configuration modal will open
3. Configure the following:
   * **Name**: Helps in selecting the correct integration for a request (does not affect functionality)
   * **Base URL**: Sets the foundation of the endpoint
   * **Key-Value Construct**: Defines parameters for query strings and request bodies

#### Key-Value Construct

The Key-Value Construct is used to define parameters that will be added to the request. There are two types of parameters:

**1. Query Parameters**

* Use the prefix `query.` for the key
* These parameters will be added to the URL as query string parameters

Examples:

| Key              | Value | Result in URL    |
| ---------------- | ----- | ---------------- |
| query.page       | 1     | ?page=1          |
| query.sort       | asc   | ?sort=asc        |
| query.filter\_by | date  | ?filter\_by=date |

Multiple query parameters will be combined:

| Key              | Value |
| ---------------- | ----- |
| query.page       | 1     |
| query.sort       | asc   |
| query.filter\_by | date  |

Result in URL: `?page=1&sort=asc&filter_by=date`

**2. Body Parameters**

* Use the prefix `body.` for the key
* These parameters will be added to the request body for POST requests

Examples:

| Key           | Value       | Result in Request Body      |
| ------------- | ----------- | --------------------------- |
| body.username | john\_doe   | { "username": "john\_doe" } |
| body.email    | <jd@ex.com> | { "email": "<jd@ex.com>" }  |
| body.age      | 30          | { "age": 30 }               |

Multiple body parameters will be combined into a single JSON object:

| Key           | Value       |
| ------------- | ----------- |
| body.username | john\_doe   |
| body.email    | <jd@ex.com> |
| body.age      | 30          |

Result in Request Body:

```json
{
  "username": "john_doe",
  "email": "jd@ex.com",
  "age": 30
}
```

<figure><img src="https://github.com/innovate42/innovate42-service-template/blob/docs/docs/_external/.gitbook/assets/Screenshot%202024-06-21%20at%2010.14.52.png" alt=""><figcaption></figcaption></figure>

### Using Integrations in a Component

To use these integrations in a component, contact Limio Support to obtain the necessary import for creating a request.

**Example Limio App Config**

```
name: "validate-post-code"
body.APIKEY: "my-key"
baseURL: https://postcodestreetnamechecker.com
```

#### Example Custom Component Usage

```javascript
const fetchData = async () => {
  const result = await appFetch(`api/integrations/generic/endpoint`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      method: "POST",
      path: "/api/post-code-validate",
      name: "validate-post-code",
      postCode: "SE1 3ER"
    })
  });
}
```

#### Example Request from Limio Backend

```
URL:
https://postcodestreetnamechecker.com/api/post-code-validate
Request Body:
{
  "postCode": "SE1 3ER",
  "APIKEY": "my-key"
}
```

The response will be passed directly back to the frontend untouched.

The image below illustrates the flow

<figure><img src="https://github.com/innovate42/innovate42-service-template/blob/docs/docs/_external/.gitbook/assets/Screenshot%202024-06-21%20at%2012.12.42.png" alt=""><figcaption></figcaption></figure>

### Important Notes

1. The request method to `api/integrations/generic/endpoint` must always be POST.
2. Parameter handling:
   * If the `method` in the body is GET, it will use the query parameters set.
   * If the `method` is POST, it will use the body parameters.
3. Any additional parameters included in the request body or query string will be preserved and passed to the integration endpoint.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.limio.com/developers/custom-components/connecting-to-external-service.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.