REST API Data Connector

The REST API data connector enables Alan to seamlessly interact with external services that implement a specific RESTful API. This type of connector offers a flexible way to dynamically access data from various services, thereby opening up new possibilities for data-driven applications.

If you have identified a use case where you want to access external services and dynamically retrieve data, the REST API data connector might be the solution you need. First, an adapter service needs to be implemented that addresses the desired system and returns the response in a format understandable by Alan. Subsequently, the REST API data connector can be configured in Alan to access the adapter service and use the data in knowledge databases.

Possible Use Cases

The REST API data connector can be used for the following use cases, for example:

• Querying current data: e.g., weather, traffic, finance, stock prices, news, real estate, sports results
• Connecting to internal systems: e.g., Customer Relationship Management (CRM), e-commerce, document management system (DMS), content management system (CMS), scheduling, event management, IoT devices, support ticket system
• Linking user data: e.g., user profiles, health data, fitness data
• Integrating an AI service that analyzes and enriches the user request (e.g., text analysis, knowledge graphs, recommendation systems)

Creating a REST API Adapter

To create a REST API data connector, first, a REST API adapter must be created. In this adapter, you need to define the required models and implement the necessary API endpoint.

Required Models

Your endpoint must accept a POST request with a JSON payload containing the following properties:

{
  "input_schema": "basic", // optional, can currently only be "basic"
  "summary": "", // optional, currently always empty
  "message": "string" // required, raw user input
}

In response, your endpoint must return a JSON object with the following structure:

{
  "documents": [
    {
      "title": "string", // optional, title of the document to display
      "external_link": "string", // optional, URL for the user to access the document
      "content": "string" // required, this text will be passed to the LLM
    }
  ]
}

Authentication

Access to the endpoint can be protected by using a custom API key. To do this, the endpoint must expect and verify the API key in the request header field X-API-KEY. The expected API key can be specified in the configuration of the REST API data connector in Alan.

OpenAPI Schema

To simplify the development process, we provide an OpenAPI schema (openapi.json) for the relevant API endpoint. This schema can be used to generate client libraries, API documentation, and other tools that work with the REST API data connector.

OpenAPI Schema

Example Implementation

For reference, we provide an example implementation in Python of a REST API adapter for the REST API data connector. Here, a simple REST API adapter is presented that returns a static response and demonstrates both the correct data models as well as authentication with an API key.

Alan Data Connector Template

Deploying a REST API Adapter

Host your REST API adapter implementation on a server that is accessible to the Alan backend. Ensure that the server can handle incoming requests and return the appropriate responses based on the defined models. Access to the endpoint must happen via HTTPS and requires a valid certificate.

Debugging the REST API Data Connection

Once a REST API adapter has been implemented and deployed, you can test it to ensure its functionality. The Alan API provides a debugging endpoint for this purpose. When called, Alan sends a test request to your REST API adapter. This tests the reachability and the response format.

To call this endpoint, you can make a POST request to the debugging endpoint (/connectors/validate-restapi) with a payload in the following format:

{
  "url": "string",
  "api_key": "string | null",
  "message": "string"
}

An easy way to do this is via the Alan Swagger documentation.

The payload is structured as follows:

• url: The URL to your REST API adapter. Ensure that this is a valid endpoint that Alan can access.
• api_key: If required, the API key for your REST API adapter; otherwise, null. The key is not stored by Alan.
• message: Populates the message field of the request to the REST API adapter.

A JSON object with the following structure is returned as a response:

{
  "success": boolean,
  "raw_response": "string | null",
  "result": "string"
}

Structure of the response:

• success: Indicates whether the test request was successfully sent to the adapter and the received response was successfully processed by Alan.
• raw_response: Contains the raw response that Alan received from the adapter. If no connection was possible, this field contains the value null.
• result: If the request was successful, this field contains the response that would be passed on to the LLM. If the request was not successful, this field contains information about the error that occurred.

With this information, you can test your REST API adapter and make improvements as needed.

Configuring a REST API Data Connector in Alan

To configure a REST API data connector in Alan, follow these steps:

1. Navigate to the Data Connectors section in the Administration area.
2. Click the New button and select the REST option.
3. Click Next and provide the required details to configure the connector, including:
   • Title: A descriptive name for the connector.
   • Description: A brief description of the connector.
   • URL: The URL of the REST API adapter endpoint (e.g., https://example.com:8000/query). It must be an HTTPS URL.
   • REST API Key: The API key required to access the endpoint. If no API key is required, this field can be left disabled. It is not possible to read the API key after saving, it can however be updated or deleted.
4. Click Save to save the configuration.

Now, knowledge databases can be created based on the REST API data connector to access external services and dynamically retrieve data.