Building an Application Handler

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

​

What are API Handlers?

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

​

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 five 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.

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.

​

API Table

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

​

Implementation

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.

  def __init__(self, name: str):
      super().__init__(name)
      """ constructor
      Args:
          name (str): the handler name
      """
  
      self._tables = {}
  

• Implementing the _register_table() method:

  The _register_table() method registers the data resource in memory.

  def _register_table(self, table_name: str, table_class: Any):
      """
      Register the data resource. For e.g if you are using Twitter API it registers the `tweets` resource from `/api/v2/tweets`.
      """
      self._tables[table_name] = table_class
  

• 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.
      Returns:
          HandlerStatusResponse
      """
  

• 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
      Returns:
          HandlerStatusResponse
      """
  

• 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.
      Args:
          query (Any): query in native format (str for sql databases,
              dict for mongo, api's json etc)
      Returns:
          HandlerResponse
      """
  

• 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.
      Args:
          query (ASTNode): sql query represented as AST. May be any kind
              of query: SELECT, INSERT, DELETE, etc
      Returns:
          DataFrame
      """
  

​

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'
type = HANDLER_TYPE.DATA
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:

• TwitterHandler

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