- Contributing Guide
- Building an Application Handler
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.
To learn more about handlers and how to implement a database handler, visit our doc page here.
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
By providing the implementation for some or all of the methods contained in the
APIHandler class, you can interact with the application apis.
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.
|It register the data resource in memory. For e.g if you are using Twitter API it registers the |
|It performs the necessary steps to connect/authenticate to the underlying system.|
|It evaluates if the connection is alive and healthy.|
|It parses any native statement string and acts upon it (for example, raw syntax commands).|
|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
mindsdb.integrations.libs.utils library, contributors can find various methods that may be useful while implementing new handlers.
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.
|It implements the mappings from the ast.Select and calls the actual api through the |
|It implements the mappings from the ast.Insert and calls the actual api through the |
|It implements the mappings from the ast.Update and calls the actual api through the |
|It implements the mappings from the ast.Delete and calls the actual api through the |
|It maps the data columns returned by the api.|
Each application handler should inherit from the
Here is a step-by-step guide:
This method initializes the handler. The
connection_dataargument contains the
CREATE DATABASEstatement, such as
def __init__(self, name: str, connection_data: Optional[dict]): """ constructor Args: name (str): the handler name """
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 """
check_connection()method performs the health check for the connection.
def check_connection(self) -> HandlerStatusResponse: """ Check connection to the handler Returns: HandlerStatusResponse """
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 """
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
versionof the handler.
nameof the handler.
typeof the handler, either
icon_pathto the file with the database icon.
titleof the handler or a short description.
descriptionof the handler.
connection_argsdictionary with the connection arguments.
connection_args_exampledictionary with an example of the connection arguments.
import_errormessage that is used if the import of the
Let’s look at an example of the
... 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:
And here are all the handlers available in the MindsDB repository.