1. Contributing Guide
  2. Building an Application Handler

In this section, you’ll find how to add new applications integrations to MindsDB.


You should have the latest staging version of the MindsDB repository installed locally. Follow this guide to learn how to install MindsDB for development.

What are API Handlers?

Aplication handlers act as a bridge between MindsDB and any application that provides APIs. You use application handlers to create databases using the CREATE DATABASE command. So, you can reach data from any application that has its handler implemented within MindsDB.

Database Handlers

To learn more about handlers and how to implement a database handler, visit our doc page here.

ML Handlers

To learn more about handlers and how to implement a machine learning (ML) handler, visit our doc page here.

Creating a Application Handler

You can create your own application handler within MindsDB by inheriting from the APIHandler class.

By providing the implementation for some or all of the methods contained in the APIHandler class, you can interact with the application apis.

Core Methods

Apart from the __init__() method, there are seven core methods that must be implemented. We recommend checking actual examples in the codebase to get an idea of what goes into each of these methods, as they can change a bit depending on the nature of the system being integrated.

Let’s review the purpose of each method.

_register_table()It register the data resource in memory. For e.g if you are using Twitter API it registers the tweets resource from /api/v2/tweets.
connect()It performs the necessary steps to connect/authenticate to the underlying system.
check_connection()It evaluates if the connection is alive and healthy.
native_query()It parses any native statement string and acts upon it (for example, raw syntax commands).
call_application_api()It calls the application API and maps the data to pandas DataFrame. This method handles the paggination and data mapping.

Authors can opt for adding private methods, new files and folders, or any combination of these to structure all the necessary work that will enable the core methods to work as intended.

Other Common Methods

Under the mindsdb.integrations.libs.utils library, contributors can find various methods that may be useful while implementing new handlers.

API table

Once the data returned from the API call is registered using the handlers _register_table, you can use it to map to the APITables class. The APITable class provides CRUD methods.

select()It implements the mappings from the ast.Select and calls the actual api through the call_application_api
insert()It implements the mappings from the ast.Insert and calls the actual api through the call_application_api
update()It implements the mappings from the ast.Update and calls the actual api through the call_application_api
delete()It implements the mappings from the ast.Delete and calls the actual api through the call_application_api
get_columns()It maps the data columns returned by the api.


Each application handler should inherit from the APIHandler class.

Here is a step-by-step guide:

  • Implementing the __init__() method:

    This method initializes the handler. The connection_data argument contains the PARAMETERS from the CREATE DATABASE statement, such as user, token, etc.

    def __init__(self, name: str, connection_data: Optional[dict]):
        """ constructor
            name (str): the handler name
  • Implementing the connect() method:

    The connect() method sets up the connection.

    def connect(self) -> HandlerStatusResponse:
        """ Set up any connections required by the handler
        Should return output of check_connection() method after attempting
        connection. Should switch self.is_connected.
  • Implementing the check_connection() method:

    The check_connection() method performs the health check for the connection.

    def check_connection(self) -> HandlerStatusResponse:
        """ Check connection to the handler
  • Implementing the native_query() method:

    The native_query() method runs commands of the native api syntax.

    def native_query(self, query: Any) -> HandlerResponse:
        """Receive raw query and act upon it somehow.
            query (Any): query in native format (str for sql databases,
                dict for mongo, api's json etc)
  • Implementing the call_application_api() method:

    This method makes the API calls.

    def call_application_api(self, method_name:str = None, params:dict = None) -> DataFrame:
        """Receive query as AST (abstract syntax tree) and act upon it somehow.
            query (ASTNode): sql query represented as AST. May be any kind
                of query: SELECT, INSERT, DELETE, etc

Exporting All Required Variables

This is what should be exported in the __init__.py file:

  • The Handler class.
  • The version of the handler.
  • The name of the handler.
  • The type of the handler, either DATA handler or ML handler.
  • The icon_path to the file with the database icon.
  • The title of the handler or a short description.
  • The description of the handler.
  • The connection_args dictionary with the connection arguments.
  • The connection_args_example dictionary with an example of the connection arguments.
  • The import_error message that is used if the import of the Handler class fails.

Let’s look at an example of the __init__.py file.

title = 'Twitter'
version = 0.1
description = 'Twitter API integration'
name = 'twitter'
icon_path = 'icon.png'

__all__ = [
    'Handler', 'version', 'name', 'type', 'title',
    'description', 'connection_args_example', 'icon_path'

Check out our Application Handlers!

To see some integration handlers that are currently in use, we encourage you to check out the following handlers inside the MindsDB repository:

And here are all the handlers available in the MindsDB repository.