Set up a project with a connector

Introduction

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

Prerequisites

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

API Builder Connectors

Connectors are adapters to 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.

NOTERefer to API Builder Connectors for detailed information.

Available connectors

The following connectors are 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 @axway/api-builder-plugin-dc-mysql

NOTE: You will need to configure your connector with connection details before starting your application or it will fail to start. For additional configuration details, refer to MySQL connector.

Configuring connectors

When you install a connector, it will create a configuration file located in the <SERVICE_FOLDER>/conf folder that 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 and port, user, password, and database.

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 table lists the configuration files, their location, and their example content. The connector configuration is shown to inform you that you will have to provide an additional set of environment variables when using an API Builder service with connectors.

Configuration File Location Example
Service Configuration <SERVICE_FOLDER>/conf/default.js
module.exports = {
 apiKey: process.env.APIKEY
 port: parseInt(process.env.PORT) || 8080
};
Connector Configuration

Example with MySQL.

The file will be named <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 generate APIs based on the methods in generated models.
      modelAutogen: false
    }
  }
};

For additional MySQL connector configuration information, refer to MySQL connector.

Using connector models

Once you've 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.

 

Related Links