Set up a project with a connector

4 minute read

Introduction

This document provides information on how to configure and run an API Builder service within a connector.

Prerequisites

Before setting up a project with a connector, refer to:

• Getting Started With API Builder - Provides detailed instructions for installing API Builder and creating an API Builder project.
• API Builder Project - Provides detailed information about API Builder projects and services.

API Builder Connectors

Data connector plugins allow you to read and write data to and from an external data source, such as Oracle, MySQL, MSSQL, and MongoDB. They give your application the ability to utilize existing data sources to create Models for use within your API Builder application, either directly as API or within flows.

Available connectors

The following data connector plugins are currently available for download directly from npm:

To install a data connector, navigate to the root directory of your service and use the following command; for example, to install the MySQL data connector:

npm install --no-optional @axway/api-builder-plugin-dc-mysql

Configuring data connector plugins

When you install a data connector plugin, it will create a configuration file located the <SERVICE_FOLDER>/conf folder and has the name of your connector. For example, mysql.default.js. You will need to edit this file and give it the required connection details such as database host/port, username, password, and database. The connector configuration contains additional set of environment variables when using an API Builder service with connectors.

The configuration files that can contain environment variables are placed in the <SERVICE_FOLDER>/conf folder.

All the variables in your configuration files taken from process.env.<VARIABLE_NAME> can be provided when running the Docker container.

The following is an example configuration file for the MySQL Connector. It will be created when api-builder-plugin-dc-mysql is installed. Note that “mysql” is a friendly name of this configuration instance. You can create multiple configuration instances with different names in this file.

// example <SERVICE_FOLDER/conf/mysql.default.js>
 module.exports = {
  connectors: {
    mysql: {
      connector: ‘@axway/api-builder-plugin-dc-mysql’,
      connectionPooling: true,
      connectionLimit: 10,
      host: process.env.MYSQL_HOST || ‘localhost’,
      port: 3306,
      // This could be set to mysql since this is already available database
      // by default
      database: ‘mysql’,
      user: process.env.MYSQL_USER,
      password: process.env.MYSQL_PASSWORD,
      // Create models based on your schema that can be used in your API.
      generateModelsFromSchema: true,
      // Whether or not to automatically generate APIs based on the methods in
      // generated models. Otherwise, models can be used in flows
      modelAutogen: false
    }
  }
};

Using connector models

Once you have configured your MySQL configuration files located under <project>/conf, you can start up your API Builder project and visit the console (normally found under localhost:8080/console ). Your MySQL tables will be listed under the Models tab of the console.

Using the auto-generated model API

To generate flow-based API endpoints, click on the Gear icon to the right of the table names. For additional information on generating API endpoints, refer to Manage Endpoints.

You can also reference the connector in a custom model.

const Account = APIBuilder.Model.extend('Account', {
  fields: {
    Name: { type: String, required: true }
  },
  connector: 'mysql'
});

If you want to map a specific model to a specific table, use metadata. For example, to map the account model to the accounts table set it as:

const Account = APIBuilder.Model.extend('account', {
  fields: {
    Name: { type: String, required: false, validator: /[a-zA-Z]{3,}/ }
  },
  connector: 'mysql',
  metadata: {
    'mysql': {
      table: 'accounts'
    }
  }
});

Using connector models in flows

To use the MySQL connector model in a flow, select the Flow icon for one of the generated endpoints for the MySQL connector; for example, for the Find all mysqlPersons endpoint. The API Orchestration page with all loaded connectors, flow-nodes, and so forth is displayed. For additional information on using a connector model in a flow, refer to Manage Flows.