Api Builder Standalone 1-21-2020 PDF

API Builder Standalone
Saved as PDF January 21, 2020

Axway Doc Portal
Copyright © 2019 Axway- All rights reserved.
No part of this publication may be reproduced, transmitted, stored in a retrieval system, or translated into any human
or computer language, in any form or by any means, electronic, mechanical, magnetic, optical, chemical, manual, or
otherwise, without the prior written permission of the copyright owner, Axway.
This document, provided for informational purposes only, may be subject to significant modification. The
descriptions and information in this document may not necessarily accurately represent or reflect the current or
planned functions of this product. Axway may change this publication, the product described herein, or both. These
changes will be incorporated in new versions of this document. Axway does not warrant that this document is error
free.
Axway recognizes the rights of the holders of all trademarks used in its publications.
The documentation may provide hyperlinks to third-party web sites or access to third-party content. Links and
access to these sites are provided for your convenience only. Axway does not control, endorse or guarantee content
found in such sites. Axway is not responsible for any content, associated links, resources or services associated
with a third-party site.
Axway shall not be liable for any loss or damage of any sort associated with your use of third-party content.
Contents
1 API Builder...................................................................................................................................................................... 7
2 API Builder Getting Started Guide..........................................................................................................................9
3 API Builder Developer Guide................................................................................................................................. 16

API Builder Console............................................................................................................................................ 17
Models........................................................................................................................................................ 24
API Builder Project.............................................................................................................................................. 27
Configuration............................................................................................................................................. 30
Project Configuration....................................................................................................................... 30
Authentication Schemes..................................................................................................................45
APIs and Endpoints................................................................................................................................... 48
Logging.......................................................................................................................................................50
Debugging.................................................................................................................................................. 51
API Builder AMPLIFY CLI.................................................................................................................................... 51
API Builder CLI.....................................................................................................................................................53
API Builder APIs.................................................................................................................................................. 54
API Builder Blocks............................................................................................................................................... 57
API Builder Connectors....................................................................................................................................... 58
MBS Connector.......................................................................................................................................... 60
Mongo Connector...................................................................................................................................... 63
MSSQL Connector..................................................................................................................................... 65
MySQL Connector...................................................................................................................................... 67
Oracle Connector....................................................................................................................................... 69
API Builder Credentials....................................................................................................................................... 72
Configuring Credentials.............................................................................................................................73
API Key credentials.......................................................................................................................... 73
HTTP Basic credentials................................................................................................................... 74
OAuth 2.0 credentials.......................................................................................................................74
Environmentalizing Credentials................................................................................................................ 80
Managing Credentials............................................................................................................................... 82
Authorization in Swagger Plugin...............................................................................................................84
API Builder Flows................................................................................................................................................ 88
Manage Endpoints.....................................................................................................................................89
Manage Flows............................................................................................................................................92
Flow Examples................................................................................................................................. 95
Count Users.............................................................................................................................95
Create a User...........................................................................................................................96
Delete All Users.......................................................................................................................98
API Builder Standalone 3

Delete a User........................................................................................................................... 99
Find All Users........................................................................................................................ 100
Find a Distinct User.............................................................................................................. 101
Find a User by ID................................................................................................................... 102
Find and Modify Users......................................................................................................... 104
Query a User..........................................................................................................................106
Update a User....................................................................................................................... 107
Upsert a User........................................................................................................................ 109
Manage flow-nodes................................................................................................................................. 110
Flow-nodes...............................................................................................................................................113
Authorization flow-node................................................................................................................ 114
Base64 flow-node.......................................................................................................................... 115
Codeblock flow-node..................................................................................................................... 116
Compose flow-node....................................................................................................................... 119
Condition flow-node....................................................................................................................... 121
Delay flow-node.............................................................................................................................. 124
DoT flow-node................................................................................................................................ 125
HTTP flow-node............................................................................................................................. 132
JSON flow-node............................................................................................................................. 132
JavaScript flow-node..................................................................................................................... 134
Model flow-nodes...........................................................................................................................141
count method........................................................................................................................142
create method.......................................................................................................................144
delete method....................................................................................................................... 144
deleteAll method...................................................................................................................145
distinct method.....................................................................................................................145
findAll method.......................................................................................................................148
findAndModify method.........................................................................................................148
findByID method................................................................................................................... 151
query method........................................................................................................................ 152
update method......................................................................................................................155
upsert method...................................................................................................................... 155
Mustache flow-node...................................................................................................................... 156
REST flow-node.............................................................................................................................. 159
Set Context flow-node....................................................................................................................166
Swagger flow-node........................................................................................................................ 167
Axway Flow SDK...................................................................................................................................... 178
API Builder Models............................................................................................................................................187
Models - Access a Model........................................................................................................................ 200
Models - Composite................................................................................................................................ 200
Models - Definition...................................................................................................................................203
Models - Predefined or Custom Endpoints............................................................................................ 206
API Builder Plugins............................................................................................................................................207
API Builder SDK................................................................................................................................................. 209
Programmatic API................................................................................................................................... 218

API Builder Web.................................................................................................................................................225
4 API Builder HOW TO..............................................................................................................................................231

Authorization: Access Gmail using Swagger flow-node.................................................................................231
Authorization: Access Microsoft OneDrive using REST flow-node................................................................261
Create a custom flow-node.............................................................................................................................. 284
Debug a flow......................................................................................................................................................288
Deploy an API Builder Standalone application to AMPLIFY Runtime Services.............................................292
Dockerize an API Builder Service..................................................................................................................... 294
Enable additional CA certificates..................................................................................................................... 301
Enable a secure HTTPS listener.......................................................................................................................303
Environmentalization........................................................................................................................................ 305
Export API Builder Logs into a Data Store....................................................................................................... 309
Import an API Builder API into API Manager................................................................................................... 316
Set up a project with a connector.................................................................................................................... 323
5 API Builder Release Notes....................................................................................................................................328

API Builder Standalone - 17 January 2020...................................................................................................... 331
API Builder Standalone - 20 December 2019.................................................................................................. 334
API Builder Standalone - 6 December 2019.................................................................................................... 337
API Builder Standalone - 22 November 2019.................................................................................................. 340
API Builder Standalone - 8 November 2019.................................................................................................... 343
API Builder Standalone - 11 October 2019...................................................................................................... 346
API Builder Standalone - 27 September 2019................................................................................................. 352
API Builder Standalone - 30 August 2019....................................................................................................... 355
API Builder Standalone - 2 August 2019..........................................................................................................360
API Builder Standalone - 19 July 2019.............................................................................................................364
API Builder Standalone - 5 July 2019...............................................................................................................367
API Builder Standalone - 21 June 2019........................................................................................................... 369
API Builder Standalone - 7 June 2019............................................................................................................. 372
API Builder Standalone - 24 May 2019............................................................................................................ 374
API Builder Standalone - 26 April 2019............................................................................................................377
API Builder Standalone - 12 April 2019............................................................................................................380
API Builder Standalone - 29 March 2019.........................................................................................................383
API Builder Standalone - 15 March 2019.........................................................................................................386
API Builder Standalone - 1 March 2019........................................................................................................... 389
API Builder Standalone - 15 February 2019.....................................................................................................393
API Builder Standalone - 1 February 2019....................................................................................................... 396
API Builder Standalone - 18 January 2019...................................................................................................... 399
API Builder Standalone - 21 December 2018.................................................................................................. 402
API Builder Standalone - 7 December 2018.................................................................................................... 405
API Builder Standalone - 23 November 2018.................................................................................................. 408

API Builder Standalone - 3 August 2018..........................................................................................................430
API Builder Standalone - 24 July 2018.............................................................................................................433
API Builder Tools 4.0.0 Release Note.............................................................................................................. 436
6 API Builder FAQ....................................................................................................................................................... 444
7 API Builder Deprecations..................................................................................................................................... 446

Change in the handling of Memory model queries using $like comparison operator..................................452
Change in the handling of comparison operators on Composite models.................................................... 455
Change in the loading of plugins when errors occur...................................................................................... 456
Change in the way config is passed to plugins............................................................................................... 457
Change in the way model name is encoded in Swagger................................................................................ 459
Change in the way model name is encoded in URI......................................................................................... 462
Change in the way model name with connector prefix is encoded in paths................................................. 463
Change in the way null fields are returned in Models..................................................................................... 464
Change in the way of handling authentication and authentication plugins.................................................. 467
Removal of Codeblocks....................................................................................................................................470
Removal of Model prefix...................................................................................................................................470
Removal of strings as default Model IDs........................................................................................................ 471
Removal of the Model instance reduce and APIBuilder.Model.reduce functions........................................ 472
Removal of unsupported APIs on Models that do not have a primary key................................................... 475
8 API Builder v3 to v4 Upgrade Guide..................................................................................................................479

API Builder
1
Overview
From API Builder V4.0.0 onward, you can now create your independent services for containerization and
deployment on your container platform of choice.
In this first version, you will be able to install the API Builder CLI, create a new project, and run it from the
command line, all without the need to create a user account or host your project on the Axway platform.
API Builder lets you build and deploy a project that is comprised of API endpoints that can be consumed by
any client application. An API Builder project is a Node.js application that runs as a service and is comprised
of several components. You can either define the components using JavaScript or JSON files placed in
specific directories, which are automatically loaded when creating an API Builder instance or
programmatically create components after initializing an API Builder instance. For information about the
components, see the sections below.
To get started, see the API Builder Getting Started Guide.
Connectors
API Builder Connectors are adapters that allow you to read and write data to and from an external data
source, such as MySQL, or in server memory. You can either add an existing connector to your application
or create one to interface with your custom data source.
Models
Models provide a standardized interface for an application that allows client applications to access data.
Models are either provided by a connector, reduced from an existing model, or composed of several models
(composite models) using a left or an inner join operation.
APIs
API Builder APIs can be automatically generated for all models, but there may be cases where you will want
to create your custom API. An API provides a way for a client to access your application, such as GET
<SERVER_ADDRESS>/api/users/query, execute custom logic, and internally access the application's
models and APIs, then return data to the client application.
Blocks
API Builder Blocks are filters that allow you to pre- or post-process data. Blocks are optional and can be
used by either APIs or Models.
Flows
API Builder Flows implement the business logic of your API. Flows are created using the Flow Editor, a rich
graphical editor.
Topics

1 API Builder
• API Builder Getting Started Guide

• API Builder Developer Guide
• API Builder HOW TO
• API Builder Release Notes
• API Builder FAQ
• API Builder Deprecations
• API Builder v3 to v4 Upgrade Guide

API Builder Getting
Started Guide 2
Prerequisites
You should have NPM (minimum 5.7), and Node.js (minimum 8.9) installed.
Getting started
Install the API Builder Command Line Interface (CLI) globally using npm.
Install API Builder

[sudo] npm install -g @axway/api-builder
Once API Builder CLI is installed, you can use it to create a new project. In the following example, the CLI will
create and initialize the ./myproject project directory.
Initialize a new project

api-builder init myproject
Then, install the project's dependencies and start the API Builder project.
Run project
cd myproject
npm install --no-optional
npm start
Once your project is running, point your browser to http://localhost:8080/console to access the
API Builder Standalone user interface (UI) console.
Upon reviewing the API Builder Standalone console, you can navigate to the following items:
Summary Your app's admin home page.
API Doc & Test Auto-generated documentation

about your API endpoints.
Provides help for the client
application to access your
application.
Models Interface to help you build

models. A model represents data
stored from another source.

2 API Builder Getting Started Guide
Configurations Lists configuration files that you

can modify and save within a
browser.
Credentials Lists the currently configured

credentials.
Connectors Lists the components to extend

the core functionality of API
Builder, and that can be used to
connect to different data sources
and services or enhance the Flow
editor.
View Documentation Links to the Axway

documentation for API Builder
Standalone.
Sidebar toggle Toggles the width of the sidebar.
Chat Click to make a suggestion or

receive product notifications.
To quickly navigate to the Summary tab, click on the Axway icon or click on API Builder.
The Admin Console is not deployed in Production installs of your application:
npm install --production --no-optional
It can also be disabled by changing the configuration settings in the conf/default.js file. For now, let's
explore some of the features of the Admin Console.
Create a new model
Let's create a new model using the Admin Console. In the Admin Console,
1. Click the Models tab.

2. Click the + Model button on the right side.

3. In the New Model step:
a. Enter "simpleuser" in the Model name field (required). The name must be unique for all of the
application's models.
b. Select a Connector from the drop-down list (required). Connectors are used to persist data to the
model.
c. Add a description.
d. Click Next to move onto the fields step.
4. In the Create Model Fields step:
a. Click the + Field button.

b. Enter "first_name" in the Field name field (required).
c. Set Type to String.

d. Leave Default value empty.
e. Add a description.
f. Check the boxes for Read-only or Required as necessary.
g. Click the Add field to model button.
h. Repeat step 4 as necessary to add the "last_name" and "email" fields to this model. After you add
the fields, you can configure them by changing properties or adding validation or return logic.
i. Click Next to move onto the endpoint step.
5. In the API endpoint page:

a. Make sure the Create, Retrieve, Update, and Delete methods are checked.
b. Click Save to commit your new model to the app.
If you look in your project's models folder, notice you have a new file called simpleuser.js. This file was
just created by the Admin Console. Instead of creating a model using the Admin Console, you can define
one using JavaScript files in the project's models folder.
Access model data
Now that you have created the simpleuser model, let's try to retrieve the model data from the application. In
the Admin Console:
1. Click the API Docs & Test tab. This page lists all the API endpoints that your application exposes. You
can also add or import API endpoints via the + API button. For additional information, refer to Manage
Endpoints.
2. Click anywhere on the row of any one of the API endpoints that you recently created. The Admin
Console presents all the API endpoints that can be used to access a particular model. You can also
export API endpoints via the Download Swagger button. For additional information, refer to Manage

Endpoints.
3. Expand one of the GET methods in your endpoint. The code example for the curl should be visible. If
it's not, scroll down until the Examples section is visible and select curl.
4. Copy a curl command and run it in a terminal. Note the message returned by this command.
Alternatively, you can test the select GET method in the user interface. Scroll until the Test API section
is visible; if available complete the Request, Path parameters, and Query parameters fields and then
click Execute. Note the Result returned in the user interface.
Providing environment-specific configuration

You can choose which configuration values you want to be configurable from the environment by explicitly
setting them in your conf/default.js using process.env. For example, to make the log level
configurable, you could do:
Example environmental configuration variables

// Log level of the main logger
logLevel: process.env.LOG_LEVEL || 'debug',
This allows you to create containers for your application that can be configured when the container is
started. The PORT is already environmentalized, so if you wish to launch API Builder on a different port, you
can set PORT as an environment variable. For example, on Unix:
Change port via env

// The port for the UI
$ PORT=8000 npm start
However, we recommend that you do not change the environmentalized port configuration in conf/
default.js as this value is used when using Docker containers.

Environmentalization guide explains how to quickly set values to the environment variables referred to in the
configuration files so they can be used during the development of the service.

API Builder Developer
Guide 3
This guide describes the API Builder console, APIs, configuration, connectors, and flows.
• API Builder Console

• Models
• API Builder Project
• Configuration
• APIs and Endpoints
• Logging
• Debugging
• API Builder AMPLIFY CLI
• API Builder CLI
• API Builder APIs
• API Builder Blocks
• API Builder Connectors
• MBS Connector
• Mongo Connector
• MSSQL Connector
• MySQL Connector
• Oracle Connector
• API Builder Credentials
• Configuring Credentials
• Environmentalizing Credentials
• Managing Credentials
• Authorization in Swagger Plugin
• API Builder Flows
• Manage Endpoints
• Manage Flows
• Manage flow-nodes
• Flow-nodes
• Axway Flow SDK

3 API Builder Developer Guide
• API Builder Models

• Models - Access a Model
• Models - Composite
• Models - Definition
• Models - Predefined or Custom Endpoints
• API Builder Plugins
• API Builder SDK
• Programmatic API
• API Builder Web
API Builder Console

Introduction
The Admin Console allows you to create applications and allows you to manage the data in your
applications.
By default, when you create a new project and run it locally, the Admin Console is enabled and available
using the http://localhost:8080/console path. You should navigate to the Admin Console in your
web browser to view what the API Builder UI has to offer.

Configuration
To configure access to the Admin Console, open the project's ./conf/default.js file, and edit
the admin key. The admin key is a dictionary of key-value pairs that control the access to the Admin
Console, such as restricting which hosts can access the Admin Console.
The admin dictionary can contain the following keys:
Key Type Default Description
allowedHosts Array<String> - Restrict access to the

Admin Console to the
specified hosts.
enabled Boolean true Set to true to enable

the Admin Console.
Example:
./conf/default.js
// Control the settings for the @axway/api-builder-admin UI console
admin: {
// Control whether the admin website is available
enabled: true,
// The hostnames or IPs from which connections to admin are allowed.
Hostnames must be resolvable on the
// server. IP ranges can also be specified. e.g. [ 'localhost',
'192.168.1.0/24', '10.1.1.1' ]
// An empty list [] will allow unrestricted access, though this is not
recommended due to security
// concerns.
allowedHosts: [
'localhost', '::1'
]
},
API Builder tabs

API Builder provides a list of tabs on the left-hand side that helps you get started building your applications.
Click the different sections of the UI to hop between functions and features of API Builder.
Summary
The Summary tab lists basic information about your application like app name, version, description, author,
license, and API key. To quickly navigate to the Summary tab, click on the Axway icon or click on API
Builder.

API Doc & Test
On startup, API endpoints are automatically generated for all models as per their default configuration. An
API provides a way for a client to access your application, such as GET <SERVER_ADDRESS>/api/
users/query, execute custom logic, internally access the application's models and APIs, and return data
to the client application.
The API Doc & Test tab in the Admin Console contains generated docs of your application APIs, including
how to call the API, multiple examples, and the ability to test the APIs. The generated docs use the
information in the description fields of your JavaScript definition files to fill in some of the information.
API definitions can also be imported by selecting the + API button. You can import an API from a Swagger
definition by either selecting a file from your local file system or entering a URL. For additional information,
refer to Manage Endpoints.

Models
A Model is the data model, backed by a connector, and exposed as an API endpoint. A model can consist of
other models or fields from other models. Once again, API Builder will generate API endpoints for your
models by default. Changes to models require a restart.
The Models tab lets you create new models. The model build process involves the following steps:
1. Name your new model, select a connector, and add a description.

2. Add fields to your new model.
3. Select the auto-generated API endpoint.

You may only build models when executing the project locally. The build console will not work in production
even if you enable the Admin Console in production.
See the Create a new model section of API Builder Getting Started Guide for instructions on how to create a
new model. For additional information on creating and editing models, refer to Models.
Configurations
The Configurations tab displays the list of configuration files on the API Builder instance. You can edit the
configuration files here.
Warning: Edits to these files will trigger a server restart once the files have been saved.
See Project Configuration for an example and settings.

Credentials
The Credentials tab displays a card view listing of all the currently configured credentials. For additional
information, refer to Managing Credentials.
Connectors
The Connectors tab lists the components to extend the core functionality of API Builder, and that can be
used to connect to different data sources and services or enhance the Flow editor. For additional
connectors and plugin information, refer to API Builder Connectors and API Builder Plugins. For additional
flow-node information, refer to Flow-nodes.

Install a listed connector
Installed connectors are shown as Installed. Additionally, the version of the installed connectors is
displayed.
To install additional listed connectors:
1. Click the Install button associated with the connector to install. Clicking the Install button will open the
Installation in progress screen.
While the connector is being installed, an Installing spinner is displayed.
Once the installation is successfully completed, the status of the screen will change to Install
complete.
2. To cancel an in-progress installation, click Cancel Installation.
3. To display the install log, click Show install log.
4. Additionally, once the connector installation is completed, click Edit <connector>.default.js to edit the
connector configuration.
5. Click Close to close the Install complete screen.
Create a connector
To create a connector, select the Create connector link and follow the instructions. For additional
information, refer to Axway Flow SDK.
Information and search

Most API Builder tabs include the title of the page, followed by an information icon and a search bar. The
information icon, when clicked, will display a short description of its function and purpose.
To locate a particular record, enter a search term in the search bar at the top to filter the table or click
Advanced to restrict the search to a specific model field.

Navigation
To quickly navigate to the Summary tab, click on the Axway icon or click on API Builder.
Models
Introduction
This guide covers the basic instructions for creating Models. Models are a way of accessing data stored in
either server memory or a backend service, such as a MySQL database, using a Connector. Models are
accessed like standard REST objects using predefined endpoints that API Builder automatically generates.
You can either create a model by defining your schema, use an existing model defined by a connector,
modify an existing model, or create a composite model by joining two or more models together.
In the Models tab, you will see a list of models (by name), connector names, descriptions, and any joins to
other models. This page allows you also to create new models, edit an existing model, and compose the
model into a new model.
Create a new model

Models can be created in many different ways, but with the user interface (UI), you don't necessarily need to
get your hands dirty with writing out code.
To create a new model using the UI:
1. Click the + Model button.

2. In the model window.
a. Enter the Model name (required).

b. Select a Connector (required).
c. Enter a Description for the new model. While this is an optional field, we encourage you to
provide a clear and concise description of what the model does.
d. Click Next to start the process of creating a new model.
3. In the New Model page, you will see the name of the model you just created with an option to edit that
name and the Connector you selected for it to use.
4. To add a new field, click the + Field button. In the model window,
a. Enter the Field name (required).
b. Select the Type for this new field.
c. Enter a Default value (optional).
d. Enter a Description.
e. Check off the Read-only or the Required boxes.
f. Click Add field to model to complete the addition of this new field.
5. Repeat step 4 as needed to add as many fields as necessary.
6. At this point, you can edit any field you created by clicking the Pencil icon at the end of the field row.
7. If the field isn't needed, you can remove it by clicking on the Trashcan icon at the end of the field row.
Warning: There is no warning for deleting a field. When you delete a field, you will not be prompted for
a confirmation of the action.
8. Click the Next button.
9. Optional: on the endpoint generation page, select the methods that will be automatically generated for
the API endpoints. When you click Next, you are brought to the API generation page where you can
optionally generate an API definition for your new model, and choose the method(s) that you wish to
generate. To generate API endpoints:
a. Select the methods that will be automatically generated for the API endpoints.
b. You can change the singular and plural values for this new model. These values are used in the
API documentation (for example, "Create a user" or "Count users"), but these values are also
used in the body of the API responses.
c. If you are satisfied with your new field(s), click the Save button.
10. Also, on this page, you can change the singular and plural values for this new model.

11. If you are satisfied with your new field(s), click the Save button.
Edit a model
To edit an existing model using the user interface:
1. Navigate to the Models tab.

2. Locate the model you wish to edit and click the Gear icon at the end of the row. A dialogue box will
open.
3. Click Edit this model. A dialogue window will open up and allow you to make changes to your selected
model.
4. You can edit the model name by clicking the Pencil icon next to the model name.
5. Locate the field you wish to edit and click the Pencil icon at the end of its row.
6. Modify the Field name, Type, Default value, or Description fields as necessary. You can also toggle the
Read-only and Required checkboxes.
7. Once you are done modifying this field, click the Update field button.
8. Repeat steps 6-7 as necessary.
9. Click the Next button.
10. Modify any of the API endpoints and the Singular and Plural fields.
11. Click the Save button if you are satisfied with your changes.
Composing a new model

To compose a new model using the user interface:

1. Click on the Gear icon at the end of the row for the model you wish to compose and select Compose
into new.
2. Enter a model name (required) and a description.
3. In the Composite Model page, you can edit the name of the composite and modify the fields (as
needed). If you want to rename the composite, click the Pencil icon and complete the fields of the
Composite Model model window as necessary. Click Update when you have finished.
4. If you wish to modify the fields of this new composite, click the Pencil icon at the end of the row for
the field in question.
5. Fill in the various fields and check the Read-only or Required checkboxes as necessary. Click Update
Field once you have finished.
6. When you are done making any modifications, click the Next button.
7. Enable or disable any auto-generated API endpoints as you see fit.
8. Modify the Singular and Plural fields as necessary.
9. Click Save to commit your new composite model.
Generate endpoints
To generate endpoints, refer to Manage Endpoints.
API Builder Project

Overview
An API Builder application is a standard Node.js application that runs in a runtime environment. This guide
covers how to manage your project.
Project structure
A project is made up of several components. To simplify development, API Builder primarily uses a strict
directory structure and naming convention to organize the application rather than configuration files.
The following is a list of directories and files that can be found in a project:

File/Folder Name Description
apis Contains API JavaScript files used to create

custom entry points for the application. For details,
see API Builder APIs.
app.js The entry point to the application if it is used as a

server. You can monitor the startup and shutdown
sequence.
blocks Contains Block JavaScript files, used to create pre-

and post-processing filters. For details, see API
Builder Blocks.
codeblocks Contains Codeblock, JSON, and Javascript files,

used for defining custom functions for use in
Flows.
The project folder structure will not
Warning:
initially include this folder. You can
create the folder and place files in the
folder. The files will be loaded on project
start.
conf Contains configuration files in JSON format for the

project and required connectors. For details, see
Project Configuration.
Dockerfile Docker configuration file. For additional

information, refer to Dockerize an API Builder
Service.
endpoints Contains Endpoint JSON files, these are OpenAPI

2.0 (Swagger) documents used to create custom
entry points for the application, with execution logic
defined by linked Flows.
flows Contains Flow JSON files, used for defining

business logic for Endpoints.
healthcheck.js Contains a script that pings a running API Builder

service to check its health. By default, this is used
in the Dockerfile.
models Contains Model JavaScript files used to define the

schema for your data. For details, see Models.
node_modules Contains project dependencies. API Builder

automatically installs any project dependencies
declared in the package.json file.

package.json NPM configuration file to declare project

dependencies and other build or runtime
configurations.
package-lock.json NPM configuration file that is generated when NPM

modifies either the node_modules tree or the
package.json file. It describes the exact tree that
was generated so that subsequent installs can
generate identical trees, regardless of intermediate
dependency updates. The npm shrinkwrap
command repurposes the package-lock.json
file into a publishable npm-shrinkwrap.json file.
For additional information on shrink wrapping a
service, refer to npm shrinkwrap. To Dockerize
your service, refer to Dockerize an API Builder
Service.
Readme.md Provides useful installation and configuration

information.
schemas Contains the schemas used within Flows.
swagger May contain Swagger files.
tests Contains the tests used to test the validity of Flows.
web Contains Web files, used to create endpoints that

render UI.
web/public Contains static assets, such as CSS, HTML, image,

or JavaScript files, for your Web interface.
Initializer file
The app.js file contains code that initializes the server instance. You can hook into the lifecycle events of
the server as well as make additional setup or middleware calls to the server or Express app instance.
app.js
var APIBuilder = require('@axway/api-builder-runtime'),
server = new APIBuilder();
// lifecycle examples
server.on('starting', function () {
server.logger.debug('server is starting!');
});
server.on('started', function () {
server.logger.debug('server started!');
});
// start the server
server.start();

Node.js version
To specify a Node.js version or a range of Node.js versions, in the package.json file, set
the engines.node key to the Node.js version or range of versions. The default Node.js version is 8.9.
package.json
"engines": {
"node": ">= 8.9"
},
Declare dependencies
The application can import any third-party modules that are supported by standard Node.js applications.
Before building a container for your application, make sure all dependencies are listed in
the dependencies field in the application's package.json file.
package.json
{
"dependencies": {
}
Configuration
This chapter describes the API Builder project and Node.js configurations. It also provides information on
the API Builder project authentication schemes.
• Project Configuration
• Authentication Schemes
Project Configuration
Introduction
API Builder uses the configuration files in the project's conf directory to initialize the application and its
connectors. Each JavaScript file in the directory should expose an object of key-value pairs. You may add
any arbitrary key-value pair beside the one described below. The values will be passed to any method that is
passed the API Builder configuration object.
Warning: API key values and session objects are auto-generated when you create a new project.
Example configuration file:
./conf/default.js Expand source

/**
* These are your configuration file defaults.
*
* You can create additional configuration files ending in *.default.js or
* *.local.js that the server will load. The *.local.js files are ignored by
* git/npm due to the .gitignore file in the conf directory. Docker will also

* ignore these files using the .dockerignore file in the project root. This
* is so you can develop your service locally using *.local.js files and keep
* your production configs in the *.default.js files.
*
* For example, you may want to develop your service using a test API key. You
* would place that API key in a *.local.js file and it would get merged over
* the API key that is already present in default.js
*
* This is a JavaScript file (instead of JSON) so you can also use environment
* variables or perform logic in this file if needed.
*/
module.exports = {
// This is your generated API key. It was generated uniquely when you
// created this project. DO NOT SHARE this key with other services and
be
// careful with this key since it controls access to your API using the
// default configuration.
// API key
apikey: '<%=apikey%>',
// This is the base url the service will be reachable at not including
the
// port
baseurl: 'http://localhost',
// Enabling this property will print out the process.env at startup
time
printEnvVars: false,
// Proxy configuration. This configuration option allows to configure
// proxy server URL that can be leveraged in plugins that do http/s
// communication.
// proxy: 'http://localhost:8081',
// Configures your http server
http: {
// This is the port the service will be bound to. Defaults to
8080.
port: process.env.PORT,
// When this flag is set to true http is disabled.
// For this to work `ssl` flag also must be configured and
used.
disabled: false
},
// SSL configuration. For a step-by-step tutorial on how to configure
SSL see:
// https://docs.axway.com/bundle/API_Builder_4x_allOS_en/page/
enable_a_secure_https_listener.html
// Note that the sample SSL code below uses the 'fs' and 'path'
modules, e.g.:
// const fs = require('fs');
// const path = require('path');
// ssl: {
// port: 8443,
// key: fs.readFileSync(path.join('.', 'ssl','key.pem'), 'utf8'),
// cert: fs.readFileSync(path.join('.', 'ssl','cert.pem'),
'utf8'),
// passphrase: 'secret'

// },
// The number of milliseconds before timing out a request to the
server.
timeout: 120000,
// Log level of the application. Can be set to (in order of most-
verbose to
// least): trace, debug, info, warn, error, fatal, none
logLevel: process.env.LOG_LEVEL || 'info',
// Prefix to use for APIs, access to which is governed via
àccessControl`.
apiPrefix: '/api',
// Control access to the service. Set the àpiPrefixSecurity` to
change
// the authentication security to APIs bound to àpiPrefix`. Note that
// different authentication security require different input
parameters.
// àpiPrefixSecurity` can be any of the following:
//
// 'none' - Disable authentication. Note that this will make all APIs
// hosted on àpiPrefix` public.
//
// 'ldap' - LDAP authentication. Requires HTTP Basic Authentication
// (RFC-2617) scheme with Base64 encoded username:password. Also
requires
// specifying configuration property named `ldap`. It should be of type
// object and should contain required property ùrl` and optional
// properties described in ldapauth-fork module docs. See:
// https://www.npmjs.com/package/ldapauth-fork#ldapauth-config-options
//
// 'apikey' - HTTP header authentication. Requires a HTTP header
ÀPIKey`
// with the API key.
//
// 'basic' - This is the default. HTTP Basic Authentication (RFC 2617)
// where the username is the àpikey`, and the password is blank.
//
// 'plugin' - A custom authentication scheme. See:
authentication_schemes.html#AuthenticationSchemes-Customauthentication
//
// If you wish any path that is not bound to àpiPrefix` to be
accessible
// without authentication, then you can explicitly add them to `public`
// paths.
accessControl: {
apiPrefixSecurity: 'basic', // none | basic | apikey | ldap |
plugin
public: []
},
// Admin UI settings. Controls the settings for the
// @axway/api-builder-admin UI console.
admin: {
// Control whether the admin website is available.
enabled: true,

// The hostnames or IPs from which connections to admin are

allowed.
// Hostnames must be resolvable on the server. IP ranges can
also be
// specified. e.g. [ 'localhost', '192.168.1.0/24',
'10.1.1.1' ]. An
// empty list [] will allow unrestricted access, though this
is not
// recommended due to security concerns.
allowedHosts: [
'localhost', '::1'
]
},
// Swagger API documentation configuration.
apidoc: {
// If you disable, the swagger API documentation will not be
available.
// If @axway/api-builder-admin is installed and enabled, this
has no
// effect.
disabled: false,
// The prefix for the swagger API documentation. Documentation
is always
// available from '{prefix}/swagger.json'
prefix: '/apidoc',
// Overides for the Swagger API documentation. These optional
// overrides tweak how the API is generated, but not how it is
hosted
// (use àpiPrefix`, `port`, and `ssl` configuration
instead). This
// allows you to tweak specific Swagger values that are useful
when
// the service is not consumed directly, such as when the
services is
// exposed through a proxy. Available options are:
//
// schemes - The transfer protocol of the service. It is an
array of
// values that must be one or more of 'http', 'https', 'ws' or
'wss'.
// e.g. ['https']
//
// host - The host (name or ip) serving the service. This MUST
be the
// host only and does not include the scheme nor sub-paths. It
may
// include a port.
//
// basePath - The base path on which the service is served
relative to
// the host. If provided, this MUST start with a leading
slash, or be
// null to specify not to use basePath.
overrides: {

// schemes: [ 'https' ],
// host: 'localhost:8080',
// basePath: '/'
}
},
// You can generally leave this as-is since it is generated for each
new
// service you created.
session: {
encryptionAlgorithm: 'aes256',
encryptionKey: '<%=session.encryptionKey%>',
signatureAlgorithm: 'sha512-drop256',
signatureKey: '<%=session.signatureKey%>',
// should be a large unguessable string
secret: '<%=session.secret%>',
// how long the session will stay valid in ms
duration: 86400000,
// if expiresIn < activeDuration, the session will be extended
by
// activeDuration milliseconds
activeDuration: 300000
},
// If you want signed cookies, you can set this value. if you don't
want
// signed cookies, remove or make null
cookieSecret: '<%=cookieSecret%>',
// Your connector configuration goes here
connectors: {
},
// Cross-Origin Resource Sharing (CORS) settings. The available
options:
//
// 'Access-Control-Allow-Origin' - List of allowed origins. The
format can
// be any (e.g. '*'), a space separated list of strings (e.g.
// 'http://foo.com http://bar.com'), an array (e.g. ['http://foo.com',
// 'http://bar.com']), or a regex expression (e.g. /foo\.com$/).
//
// 'Access-Control-Allow-Credentials' - Adds the header to responses.
This
// response header tells browsers whether to expose the response to
frontend
// JavaScript code when the request's credentials mode
// (`Request.credentials`) is ìnclude`.
//
// 'Access-Control-Allow-Methods' - Only these methods will be allowed
(out
// of all available HTTP methods) for an endpoint. All available
methods
// are allowed by default (format: comma separated string or, an array:
// e.g. 'GET' or 'GET, PUT' or ['GET', 'PUT'])
//
// 'Access-Control-Allow-Headers' - Allowed request headers (format:
comma

// separated string or, an array: e.g. 'content-type, authorization' or

// ['content-type', 'authorization']) 'Access-Control-Allow-Headers':
// ['content-type', 'authorization']
//
// 'Access-Control-Expose-Headers' - List of response headers exposed
to the
// user. Always exposed headers: request-id, response-time and any
headers
// defined in the endpoint (format: comma separated string or, an
array:
// e.g. 'content-type, response-time' or ['content-type', 'response-
time'])
// 'Access-Control-Expose-Headers': ['content-type', 'response-time']
//
cors: {
// 'Access-Control-Allow-Origin': '*'
},
// Health check configuration. The path to a file which exports an
express
// middleware function used as a healthcheck. For more information on
// express middleware functions, see:
// https://expressjs.com/en/4x/api.html#middleware-callback-function-
examples
//
// This healthcheck middleware is executed by invoking
// "GET /apibuilderPing.json". By default, invoking this endpoint will
// return {success: <bool>} where <bool> is `true` as long as the
service
// shutting down.
//
// healthCheckAPI: './healthCheck.js',
// Flags configuration. Enable features that are not ready for
// production, or whose use may require manual upgrade steps in legacy
// services.
flags: {
// Enable support for aliases in comparison operators on
composite
// models. Breaking change for old versions as previously
queries $lt,
// $gt, $lte, $gte, $in, $nin, $eq would not have translated
aliased
// fields.
enableAliasesInCompositeOperators: true,
// Enable support for the $like comparison operator in the
Memory
// connector.
enableMemoryConnectorLike: true,
// Enable support for Models that have no primary key.
Breaking change
// for old versions as previously the Create API returned a
location
// header. Also the model advertised unsupported methods.
enableModelsWithNoPrimaryKey: true,
// Generate APIs and Flows that user primary key type rather

than always
// assuming string. Breaking change for old versions as the
generated
// APIs will change when enabled.
usePrimaryKeyType: true,
// Enabling this flag will cause the service to exit when
there is a
// problem loading a plugin
exitOnPluginFailure: true,
// Enabling this flag ensures that a plugin only receives the
config
// relevant to that plugin.
enableScopedConfig: true,
// Enable support for null fields coming from Models
enableNullModelFields: true,
// Enable support for model names being percent-encoded as per
RFC-3986
// in auto-generated API. Breaking change for old versions as
previously
// names like "foo/bar" will now be encoded as "foo%2Fbar"
enableModelNameEncoding: true,
RFC-3986
// in API Builder's Swagger. Breaking change for old versions
as
// previously names like "foo/bar" will now be encoded as "foo
%2Fbar"
enableModelNameEncodingInSwagger: true,
// Enable support for model names being encoded whilst
preserving the
// connector's slash. This flag only applies when
// enableModelNameEncodingInSwagger is enabled. Breaking
change for old
// versions as previously model names that start with a
connector name,
// e.g. "oracle/foó" will now be encoded as "oracle/fo%C3%B3".
enableModelNameEncodingWithConnectorSlash: true
},
authorization: {
callback: '/auth/callback',
credentials: {
}
}
};
Settings
The following topics describe the project configuration settings.
admin
[object] Configures the Admin Console. The admin object may contain the following key-value pairs:

allowedHosts Array<String> - Restricts access to the

Admin Console to the
specified hosts.
apiDocPrefix String '/apidoc' Deprecated [D002].

Prefix for the API
documentation.
disableAPIDoc Boolean false Deprecated [D003]. Set

to true to display the
generated Swagger API
Docs. Changing the
setting only works in
production. Swagger
documentation is
always available in dev
mode.
enabled Boolean true Set to true to enable

the Admin Console.
apidoc
[object] Configures the Swagger API documentation since the API Builder Standalone - Boston release. The
apidoc object may contain the following key-value pairs:
disabled Boolean false Set to true to display

the generated Swagger
API Docs. Changing the
setting only works in
production. Swagger
documentation is
always available in dev
mode.
prefix String '/apidoc' Prefix for the API

documentation.
overrides object {} Overrides to Swagger

documentation. Any
values set here do not
change the functionality
of the server, only what
is exposed in the
Swagger.

overrides.host string - Hostname and optional

port on which the server
can be accessed.
overrides.schemes array - Schemes which the

server can be accessed
using. Can be an array
containing any of http,
https, ws, or wss.
overrides.basePath string - The root path on which

the APIs hosted by the
server are available. If
provided, this must start
with a leading slash (/).
The value can be set to
null to clear the
basePath.
apikey
[string] Generated API key.
apiPrefix
[string] Required. Defaults to /api, and must start with a leading slash (/).
The apiPrefix forms the base of all secured API in the API Builder service that you are
developing. Authenticated access to all APIs that are bound to apiPrefix is controlled
via accessControl.
For example, the model "testuser" has its API bound to /api/testuser, the "testapi" has its API bound
to /api/testapi, and the API endpoint examlple for Greet flow is bound to /api/greet.
The apiPrefix is an important consideration when you are designing your API for use as an API endpoint in
API Builder. You might design your API so that all methods start with /api. For example, you might design
your API as /api/v1/calendar. However, when it is imported into API Builder, your path will be bound
to /api/api/v1/calendar, which is not what you want. To achieve the desired result, the API needs to
be designed without the apiPrefix. The recommendation is to design your API with a versioned basePath "/
v1", and then design your paths; for example, "/calendar". Your designed API, including its basePath, would
have the method /v1/calendar, but when imported into API Builder, it would be accessible as /api/v1/
calendar.
To clarify, your Swagger 2.0 for this API might look similar to this:
API design without API prefix

basePath: '/v1',
paths: {
'/calendar': {
get: {}
}
}

accessControl
[object] Configures authentication access since the API Builder Standalone - Kobe release. The
accessControl object may contain the following key-value pairs:
apiPrefixSecurity string none Configures the

authentication scheme
to use on APIs that are
hosted on apiPrefix.
The built-in schemes are
none, basic, apikey,
and ldap. Also, it is
possible to set this to
"plugin" to provide
custom authentication.
public array - An array of paths that

are always accessible.
The paths are prefixes,
do not support any
regex or
parameterization, and
should always start with
a slash (for example, /
foo). If "/foo" is a
public path, then it is a
path prefix ("/foo/")
such that all children are
also public (for example,
"/foo/bar"). If admin
UI is enabled, then /
console and /
adminapi are
automatic public paths.
If apidoc is enabled,
then /apidoc
(apidoc.prefix) is also
added.
plugin string - When

apiPrefixSecurity
is set to "plugin", this
should be the plugin
module to load (see
Custom Authentication).
APIKeyAuthPlugin
[string] Path to the authorization module js file. Only used if APIKeyAuthType is set to plugin.

For details, see Authentication Schemes. This key is deprecated [D010], use accessControl instead.
APIKeyAuthType
[string] Value indicating the authorization type for the application. By default, it is set to 'basic'.
For details, see Authentication Schemes. This key is deprecated [D010], use accessControl instead.
connectors
[object] Configures the connectors used by the application. The connectors field is an object of key-value
pairs where the key is the name of the connector, and the value is another key-value pair object used to
configure the connector. The configuration object is specific to each connector.
Most connectors will have a default configuration file in the conf directory.
cookieSecret
[string] If you want signed cookies, you can set this value. If you don't want to sign cookies, remove this
value, or make it null.
cors
[object] Configures the CORS settings. The cors object may contain the following key-value pairs:
Key Type Description
Access-Control-Allow-Origin String Specifies the URI that can access

the server. Defaults to none.
Access-Control-Allow-Credentials Boolean Specifies whether or not to allow

access by credentials.
Access-Control-Allow-Methods String<comma separated or If specified, only the listed

array> methods will be allowed. All
available methods are allowed by
default.
Access-Control-Allow-Headers String<comma separated or Allowed request headers.

array>
Access-Control-Expose-Headers String<comma separated or List of response headers

array> exposed to the user.
proxy
[string] Configuration option for configuring the proxy server URL that can be leveraged in plugins that do
HTTP or HTTPS communication.
Example:
proxy: http://localhost:8081

flags
[object] Flags to enable features that are not ready for production or whose use may require manual
upgrade steps in legacy services.
enableAliasesInCompositeOperat Boolean Enable support for comparison

ors operators - $lt, $gt, $lte,
$gte, $in, $nin, $ne, and $eq -
on aliased fields in Composite
models. Previously, attempting to
use these operators on aliased
fields would result in unexpected
behavior. The old functionality is
deprecated [D007], so enabling
this feature is recommended.
enableMemoryConnectorLike Boolean Enable $like comparison

operator support in models
based on the Memory connector.
Previously, attempts to perform
these queries would just have
returned an empty result set. The
old functionality is deprecated
[D008], so enabling this feature is
recommended.
enableModelsWithNoPrimaryKey Boolean Enable support for Models that

do not have a primary key. The
enableModelsWithNoPrimar
yKey feature is a breaking
change for previous API Builder
Standalone versions, as Create
API previously returned a location
header. Also, the model
advertised unsupported
methods. The old functionality is
usePrimaryKeyType Boolean Generate APIs and Flows that

use primary key type for the
Model ID instead of assuming
that the Model ID is a string.
The usePrimaryKeyType
feature is a breaking change for
previous API Builder Standalone
versions, as the generated APIs
will change when the feature is
enabled. The old functionality is

exitOnPluginFailure Boolean Enabling this flag will cause the

service to exit when there is a
problem loading a plugin. The old
functionality is deprecated
recommended.
enableScopedConfig Boolean Enabling this flag ensures that a

plugin only receives the config
relevant to that plugin. The old
recommended.
enableNullModelFields Boolean Enable support for null fields

coming from Models. The old
recommended.
enableModelNameEncoding Boolean Enable support for model names

being percent-encoded as per
RFC-3986 in auto-generated API.
The old functionality
is deprecated [D012], so enabling
enableModelNameEncodingInSw Boolean Enable support for model names

agger being percent-encoded as per
RFC-3986 in API Builder's
Swagger. The old functionality is
enableModelNameEncodingWith Boolean Enable support for model names

ConnectorSlash being encoded while preserving
the connector's slash. The old
recommended.
logLevel
[string] Sets the log level for the logger utility. Accepted values are (in order of most-verbose to least) trace,
debug, info, warn, error, fatal, none.
session
[object] You can generally leave this as-is since it is generated for each new project you create. The
session object may contain the following key-value pairs:

encryptionAlgorithm String aes256 Encryption algorithm.
encryptionKey String - Encryption key.
signatureAlgorithm String sha512-drop256 Signature algorithm.
signatureKey String - Signature key.
secret String - Should be a large un-

guessable string.
duration String 86400000 How long the session

will stay valid in
milliseconds.
activeDuration String 300000 The session will be

extended by
activeDuration
milliseconds.
port
[number/string] The port to listen on for HTTP requests. Defaults to 8080. This key is deprecated [D038],
use http.port instead.
http
[object] Your HTTP configuration goes here:
port Number The port to listen on for HTTP

requests.
disabled Boolean False by default. When this flag is

set to True HTTP traffic is
disabled.
For this to work, baseurl should
point to https path and ssl must
be configured and used.
ssl
[object] Your SSL configuration goes here. The options are the same as what is used by Node.js
https.createServer() method. A subset is as follows:

port Number The port to listen on for HTTPS

requests.
key String/Buffer/Array Private keys in PEM format. PEM

allows the option of private keys
being encrypted. Encrypted keys
will be decrypted with
options.passphrase. Multiple
keys using different algorithms
can be provided either as an
array of unencrypted key strings
or buffers, or an array of objects
in the form {pem: <string|
buffer>[, passphrase:
<string>]}. The object form
can only occur in an array.
object.passphrase is
optional. Encrypted keys will be
decrypted with
object.passphrase if
provided, or
options.passphrase if it is
not.
cert String/Buffer/Array Cert chains in PEM format. One

cert chain should be provided per
private key. Each cert chain
should consist of the PEM
formatted certificate for a
provided private key, followed by
the PEM formatted intermediate
certificates (if any), in order, and
not including the root CA (the
root CA must be pre-known to the
peer, see ca). When providing
multiple cert chains, they do not
have to be in the same order as
their private keys in key. If the
intermediate certificates are not
provided, the peer will not be able
to validate the certificate, and the
handshake will fail.
passphrase string Encrypted keys will be decrypted

with this if provided.
timeout
[number] The number of milliseconds before timing out a request to the server.

healthCheckAPI
[string] Path to a file that exports an express middleware function, which is used as a healthcheck.
See Middleware callback function examples for more information on express middleware functions.
This healthcheck middleware is executed by invoking GET /apibuilderPing.json. By default, invoking

this endpoint will return { success: <bool> }, where <bool> is true as long as the service is not
shutting down.
Example:
default.js
healthCheckAPI: '../healthCheck.js'
../healthCheck.js
module.exports = function (req, resp) {
return resp.json({ success: 'Service is up' });
}
Configuration files
API Builder will look for two sets of configuration files in the ./conf directory of the application, those
ending in default.js and local.js. The default files are part of the source for your application,
whereas the local files might contain sensitive information (such as passwords) and are not source
controlled (these files will be ignored by the Git repository). At startup, all default files are loaded and
sorted and merged into a single configuration object. Then, all local files are loaded, sorted, and merged
with the single configuration object.
Usually, the values for configuration parameters are directly specified in the configuration file. However, for
sensitive information, those values could be environmentalized. For how to do that, refer to the
Environmentalization guide. The important thing to know is that if environmentalization is used, all the
values will come as strings and might need subsequent type conversion like this:
default.js
module.exports = {
// In this case we convert the string value that comes from the environment
to integer. Similar approach would be with floats.
timeout: parseInt(process.env.TIMEOUT, 10),
// In this case we convert the string value to boolean

printEnvVars: process.env.PRINT_ENV_VARS === "true"
}
Authentication Schemes
Introduction
An API Builder project provides different types of security mechanisms to authenticate requests. Typically,
you want to restrict which client applications have access to your APIs, and you want the client to prove it
has permission to access your API Builder application's APIs.
By default, a new API Builder project uses HTTP basic authentication. A new API Builder project contains a
generated API key, apikey, located in the conf/default.js file. You may change the value of the key,

but make sure you generate a sufficiently unique key and do not share the key with other API projects as it
controls access to your API. The key should only be used by one API Builder project.
To change the authentication mechanism, open the conf/default.js file, and change the
accessControl.apiPrefixSecurity key to one of the following:
• none : No authentication. The client does not need any authentication to access these APIs. In this
case, all client requests are accepted without any security. Use the value none for the key
accessControl.apiPrefixSecurity.
• basic : Use HTTP basic authentication (default). The client uses the HTTP Authorization header
to send an encoded version of the API Key using the HTTP Basic Authentication standard. The
username part is the value of the API Key, and the password part should be blank (empty string).
• apikey : Use HTTP header authentication. The client sets the HTTP APIKey header to the value of the
API Key. In this scenario, the server must only support HTTPS endpoints, so the key is not passed in
plain text.
• plugin : Use a custom authentication mechanism. Using the plugin authentication, you can extend the
authentication to use any third-party or custom API authentication. To use your plugin, you must also
set the accessControl.plugin key to the location of your plugin. The location can be a file path
(relative to the current work directory of your server project directory) or the name of a dependency
available in node_modules.
The following headers describe the available authentication mechanisms.
HTTP basic authentication

In HTTP basic access authentication, the client needs to send a username and password, sent as a base-64
encoded string "<username>:<password>", in the Authorization header of the HTTP request. The server
should be configured only communicate over HTTPS, so the header is not sent as plain text (unencrypted).
GET api/model HTTP/1.0

Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
For API Builder applications, the username is the API key, and the password field is left blank.
HTTP header authentication

In HTTP header authentication, the client sends the API key in a custom APIKey header. The server should
be configured only communicate over HTTPS, so the key is not sent as plain text (unencrypted).
var xhr = Ti.Network.createHTTPClient({

onload: function onLoad() {
alert(`Loaded: ${this.status}: ${this.responseText}`);
},
onerror: function onError() {
alert(Èrror: ${this.status}: ${this.responseText}`);
}
});
xhr.open('GET', REQUEST_URL);
xhr.setRequestHeader('APIKey', API_KEY);
xhr.send();

Custom authentication plugin

To use a custom authentication mechanism, you need to create a CommonJS module that exposes a plugin
class and implements the following methods. All methods are optional, but to validate requests, you need to
implement the validateRequest method, either the synchronous version or asynchronous version.
Method Signature Description
Plugin(server) Constructor. Passed the server instance. The

passed server instance has not registered any
models or connectors and has not been started.
Plugin.prototype.matchURL(request): Boolean Determines if the URL should be authenticated by

the plugin. Return true if the plugin should handle
the validation else return false. This method is
deprecated. It is unsafe and should not be used.
Plugin.prototype.validateRequest(request, Validates the request synchronously. Return a

response): Boolean Boolean value indicating if the request passed
validation (true) or not (false). Do not implement if
you implemented the asynchronous version of this
method.
Plugin.prototype.validateRequest(request, Validates the request asynchronously. Pass the

response, callback): void callback an Error as its first argument (or null if
successful) and a Boolean indicating if validation
was a success or not as its second argument. Do
not implement it if you implemented the
synchronous version of this method.
Plugin.prototype.getSwaggerSecurity Used by Swagger generation to describe the

Swagger Definitions Object and the Swagger
Requirement Object authentication mechanism.
In the conf/default.js file, set the accessControl.plugin key to the location of the plugin file or the
name of the flow-node module if you specify it as a dependency in the package.json file.
For example, if your client applications send a custom header, called X-Secret, for each request and you
want to check the value sent with the request against one stored in your configuration file, you can use the
plugin below.
conf/default.js
module.exports = {
...
accessControl: {
apiPrefixSecurity: 'plugin',
plugin: './lib/plugin.js'
},
secret: 'secret'
...
}

lib/plugin.js Expand source

// Constructor to get a reference to the config object
function Plugin(server) {
this.config = server.config || { secret: null};
}
// Check if the request has the X-Secret header and its value matches the
config file
Plugin.prototype.validateRequest = function(request, response) {
if (request.headers['x-secret'] && request.headers['x-secret'] ===
this.config.secret) {
return true;
} else {
return false;
}
};
// Describe the x-security header for the Swagger 2.0 feed

Plugin.prototype.getSwaggerSecurity = function () {
return {
securityDefinitions: {
app_auth: {
type: 'apiKey',
name: 'x-secret',
in: 'header',
description: 'Require authorized access to API'
}
},
security: [{
app_auth: []
}]
}
}
module.exports = Plugin;
To test the plugin, add the -H 'X-Secret: secret' command-line option to the cURL request.
$ curl "http://127.0.0.1:8080/api/foo"
{"id":"com.appcelerator.api.unauthorized","message":"Unauthorized","success":fa
lse}
$ curl "http://127.0.0.1:8080/api/foo" -H 'X-Secret: secret'
{"success":true,"request-id":"0d2141f7-57ea-4c78-82cf-b6fa9497c16a",
"foo":"bar"}
APIs and Endpoints

APIs are defined as Swagger documents which can contain one or more Endpoint definitions. The API
Swagger document must be formatted as JSON and contained within the /endpoints directory of your
application.

When API Builder reads these API Swagger definitions, it will create the specified routes for each Endpoint.
The implementation of the business logic for each Endpoint is handled by the Flow associated with the
Endpoint. This is delegated to Flows which are specified on a per-endpoint level.
APIs have the following extensions to the Swagger specification:
Property Description Required Type Default Example
x-enabled If the API No object { "enabled" { "enabled"

should be : true } : false }
bound to the
app on load.
x-flow The name of Yes string "GreetFlow"

the Flow to be
executed when
the endpoint is
hit.
Example
This example API below is similar to the one that comes with every API Builder Project. It contains an
Endpoint which takes a username, invokes the flow called “GreetFlow”, and returns a greeting. However,
since it has an x-enabled flag set, the Endpoint will be disabled, and no requests will be able to be made to it.
Expand source
{
"x-enabled": {
"enabled": false
},
"swagger": "2.0",
"info": {
"description": "Greeting functions",
"version": "1.0.0",
"title": "Greeting API"
},
"paths": {
"/greet": {
"get": {
"x-flow": "GreetFlow",
"description": "",
"operationId": "Greet",
"parameters": [
{
"description": "The username",
"in": "query",
"name": "username",
"required": true,
"type": "string"
}
],
"produces": [
"application/json"

],
"responses": {
"200": {
"description": "greeting",
"schema": {
"$ref": "schema:///schema/myproject/greeting"
}
},
"400": {
"description": "bad request",
"schema": {
"$ref": "schema:///schema/myproject/error"
}
}
},
"summary": "Greet a user",
"tags": [
"helloworld"
]
}
}
}
}
Logging
This section provides information on API Builder logging components. API Builder streams log messages to
the console, enabling integration with third-party log aggregation tools. For additional information on
integrating API Builder logging with a third-party log aggregation tool, refer to Export API Builder Logs into a
Data Store.
Configure logging
The logLevel can be set in the configuration. See Project Configuration.
Logger programmatic interface

The Logger interface allows you to log directly from the API Builder programmatic interface.
Static properties
• DEBUG: (Number) - Constant indicating the debug level.
• ERROR: (Number) - Constant indicating the error level.
• FATAL: (Number) - Constant indicating the fatal level.
• INFO: (Number) - Constant indicating the info level.
• TRACE: (Number) - Constant indicating the trace level.
• WARN: (Number) - Constant indicating the warn level.
• NONE: (Number) - Constant indicating the none level.

Instance methods
• debug( [params] ): Logs a message with a debug-level severity. If no arguments are passed, returns a
boolean indicating if the debug level is enabled.
• error( [params] ): Logs a message with an error-level severity. If no arguments are passed, returns a
boolean indicating if the error level is enabled.
• fatal( [params] ): Logs a message with a fatal-level severity. If no arguments are passed, returns a
boolean indicating if the fatal level is enabled.
• info( [params] ): Logs a message with an info-level severity. If no arguments are passed, returns a
boolean indicating if the info level is enabled.
• level( [level] ): Sets or retrieves the log level.
• levels( [stream], [level] ): Sets or retrieves the log level for a specific stream. If no arguments are
passed, retrieves an array of available log levels. If the stream is passed, retrieves the current log level
of the stream.
• stripColors( string ): Removes ANSI color codes from the string.
• trace( [params] ): Logs a message with a trace-level severity. If no arguments are passed, returns a
boolean indicating if the trace level is enabled.
• warn( [params] ): Logs a message with a warn-level severity. If no arguments are passed, returns a
boolean indicating if the warning level is enabled.
Static methods
• createDefaultLogger( options ): Creates a log utility instance.
• createLogger( options ): Creates a log utility instance.
• createRestifyLogger( API, options ): Creates a restify version of the log utility.
Logs format
The API Builder logs use the JSON logging utility.
All logs are listed in the console each time you run your APP.
The Request/Response Logs have a specific format (for example ID, Name, and Data ).
Debugging
Once your application is successfully generated, you can run the project in debug mode using the following
command. Running the project in debug mode provides you with an opportunity to debug your application.
cd ./myproject
node --inspect-brk app.js
API Builder AMPLIFY CLI

Note

The AMPLIFY CLI is a companion CLI for the Axway AMPLIFY platform. It can be used to create API Builder
Standalone projects and initialize them with Swagger specifications that are downloaded from the AMPLIFY
Catalog. If you are using API Builder without the platform, you can optionally use the API Builder CLI instead.
API Builder AMPLIFY CLI

This document will guide you through the steps necessary to use API Builder with the Axway AMPLIFY
Platform CLI.
Installation
If you have not already installed the AMPLIFY CLI, you can install via npm:
Install @axway/amplify-cli
$ [sudo] npm install -g @axway/amplify-cli
Use the AMPLIFY CLI package manager to install the API Builder CLI
Install @axway/amplify-builder-cli
$ amplify pm install @axway/amplify-api-builder-cli
Getting started
Log in to the Axway AMPLIFY Platform using the following command:
AMPLIFY login
$ amplify auth login --client-id apicentral
Then, initialize a new API Builder Standalone project and specify the --get-catalog option. This will use
the current AMPLIFY user session to download the proxy services available from API Central. The command
will create the project, download the proxy services, and execute a npm install in the
myproject directory.
Create new API Builder project

$ amplify builder init --get-catalog myproject
AMPLIFY API Builder CLI, version 1.1.2
Copyright (c) 2019, Axway, Inc. All Rights Reserved.
Using account: apicentral:user@company.com
✔ Create project directory: myproject
✔ Fetching API Catalog
✔ Installed marketo_129818
✔ Installed slack_126453
✔ Installed another-api-builder-service
✔ Install dependencies
Successfully created: myproject. To run:
cd myproject
npm start
If you want to download only specific catalog entries, you can optionally supply a filter, which is evaluated as a regular expression:
Create new API Builder project

$ amplify builder init --get-catalog --filter="Marketo" myproject

API Builder CLI

This document will walk you through the process of how to create and initialize new projects using the API
Builder CLI.
Setup
We recommend using the command-line interface (CLI) with npx. This will ensure you are always working
with the latest CLI.
npx @axway/api-builder
However, it is possible to install the API Builder CLI if you wish:
[sudo] npm install -g @axway/api-builder
Create a project
To create a new project:
npx @axway/api-builder init myproject
The CLI will create and initialize the ./myproject new project directory.
Create a plugin
To create a new plugin:
npx @axway/api-builder plugin init myplugin
The CLI will create and initialize the plugin in a new directory ./api-builder-plugin-myplugin.
CLI commands
Command Arguments Description
api-builder init <dir> dir - The directory to initialize. Creates and initializes a new API
Builder project by creating the
project in a directory specified by
dir. The command will fail if the
directory exists or if the
command is run within an API
Builder project directory.
api-builder plugin init dir - The directory to initialize. Creates and initializes a new API
<dir> Builder plugin by creating a
directory specified by dir. The
dir must be prefixed with "api-
builder-plugin-name". If dir is not
prefixed, the prefix will be added
for you.

API Builder APIs

Introduction
This chapter covers the basic instructions for creating APIs. APIs can be automatically generated for all
models, but there may be cases where you will want to create a custom API.
An API provides a way for a client to access your application, such as GET <SERVER_ADDRESS>/api/
users/query, execute custom logic, and internally access the application's models and APIs, then return
data to the client application.
API endpoint definition

Place all API definition files in the project's apis folder. You can only declare one endpoint definition per
file. An API definition file is a JavaScript file, which:
1. Loads the @axway/api-builder-runtime module.

2. Calls the module's API.extend() method, passing in an object defining the API endpoint and logic.
3. Exports the defined endpoint using the module.exports variable.
Set the following keys in the object passed to the API.extend() method to define the API endpoint:
Name Required Description
group true The logical name for grouping

API endpoints.
path true Request path (for

example /api/user/:id).
Prefix parameters with a colon
(:).
method true HTTP verb (GET, POST, PUT, or

DELETE).
description true Description of the endpoint,

which is used in the generation of
the API endpoint documentation.
model true The model to use for the

response. An API endpoint can
only specify one model, but
models can be composed of
other models and fields.
before false One or more API Builder Blocks

to be executed before the
request. Blocks are referenced by
their name property. If you want
to execute multiple blocks, you
should specify them as an array

of block names. If multiple

blocks are specified, they are
executed in the order specified.
after false One or more API Builder Blocks

to be executed after the request.
Blocks are referenced by
their name property. If you want
to execute multiple blocks, you
should specify them as an array
of block names. If multiple
blocks are specified, they are
executed in the order specified.
action true A function that is called to

execute the API endpoint’s logic.
The function is passed a
request object, response
object, and next() method. Use
this function to make
programmatic calls to your
model’s methods for reading and
writing data, and to do other
things related to the custom
business logic of your API
endpoint, including making calls
to other flow-node modules that
your API endpoint requires. You
should always make sure that
your action function calls
the next function regardless if
the result is a success or an
error.
parameters false Input parameters required to

execute the API endpoint. This is
an object of key-value pairs,
where the key is the name of the
parameter, and the value is an
object with the following
properties:
• optional
(Boolean): Determines if the
parameter is optional
(true) or required (false).
• type (String): the type of
input parameter: path,
query, or body.

• description (String):
used for generating API
documentation.
API example
The following API definition file creates an endpoint that can be accessed by a client
using GET <HOST_ADDRESS>/api/test/:id. Before the request is initiated by the server,
the pre_example is executed, then the server performs the request (executes the action logic). The action
logic tries to find the user model with the specified ID. After the logic executes, the post_example is
executed.
apis/testapi.js
var APIBuilder = require('@axway/api-builder-runtime');
var TestAPI = APIBuilder.API.extend({

group: 'testapi',
path: '/api/testapi/:id',
method: 'GET',
description: 'this is an api that shows how to implement an API',
model: 'testuser',
before: 'pre_example',
after: 'post_example',
parameters: {
id: { description: 'the test user id' }
},
action: function (req, resp, next) {
// invoke the model find method passing the id parameter
// stream the result back as response
resp.stream(req.model.find, req.params.id, next);
}
});
module.exports = TestAPI;
Invoke API endpoints in API Builder

Any callback in the application that is passed the request object can access the endpoints
programmatically.
To invoke an API endpoint:
1. Retrieve an instance to API Builder using the request.server property.

2. Retrieve the API instance using API Builder's get API (endpoint, verb) method by passing it the
endpoint without the server host or address as the first parameter and the HTTP verb as the second
parameter.
3. Invoke the execute(params, callback) method on the API instance by passing it a dictionary of
parameters as the first parameter and a callback function as the second parameter. The callback
function is passed an error and results object.
Example:

The Route below is invoking the GET <SERVER_ADDRESS>/api/car method programmatically.
web/routes/testroute.js
var TestRoute = APIBuilder.Router.extend({
name: 'car',
path: '/car',
method: 'GET',
description: 'get some cars',
action: function (req, res, next) {
req.server.getAPI('api/car', 'GET').execute({}, function(err, results)

{
if (err) {
next(err);
} else {
req.log.info('got cars ' + JSON.stringify(results));
res.render('car', results);
}
});
}
});
module.exports = TestRoute;
API Builder Blocks

Introduction
This guide covers the basic instructions for creating Blocks. Blocks are functions that run before or after an
API endpoint is executed. They can be used to modify the API request, to modify the API response or to
execute common tasks like audit logging, caching, rate-limiting, or recording analytics. Multiple Blocks can
be executed before or after an API request. Blocks are optional.
Block definition
Place all Block files in the project's blocks folder. You can only declare one Block per file. A Block file is a
JavaScript file, which:

2. Calls the module's Block.extend() method, passing in an object defining the block identifier and
logic to execute.
3. Exports the defined block using the module.exports variable.
Set the following keys in the object passed to the Block.extend() method to define the Block:
name true Block name. This name should

be used when specifying blocks
in your API endpoint definition.
Assign the name value to either

the before or after property in

the API definition object to use it.
description true Human useful description to

display in the documentation.
action true The function containing the logic

for your block. All of your
runnable code goes in the
action function. This function is
passed a request and
response.
Example
The following Block sets the set parameter and logs the change.
var PreBlock = APIBuilder.Block.extend({

name: 'pre_example',
description: 'will set a header named "Foo"',
action: function (req, resp) {

// this is a synchronous block since it doesn't have a nex
resp.set('Foo', 'Bar');
req.log.info('Pre Example Block executed');
}
});
module.exports = PreBlock;
API Builder Connectors

Data connector plugins allow you to read and write data to and from an external data source, such as
Oracle, MySQL, and MongoDB. They give you the power to interact with your data as part of your flow and
create feature-rich microservices. For information on the Connectors UI, refer to API Builder Console.
Currently available
The following data connector plugins are currently available for download directly from npm:
• MBS Connector
• Mongo Connector
• MSSQL Connector
• MySQL Connector

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 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/ module.exports = {

default.js apiKey:
process.env.APIKEY
port:
parseInt(process.env.POR
T) || 8080
};
Connector Configuration Example with MySQL. module.exports = {

The file will be named connectors: {
<SERVICE_FOLDER> /conf/ mysql: {
connector:
mysql.default.js
'@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_PASSWO
RD,
// 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
}
}
};
Additional information
For additional information on the connectors:
• MBS Connector
• Mongo Connector
• MSSQL Connector
• MySQL Connector
MBS Connector
The Axway Mobile Backend Services (MBS) connector is a plugin for API Builder that can connect to an
MBS instance on the Axway platform that you can use to store your Model data. The Models can be used
programmatically or can be used within the flow editor to interact with your MBS instance.
Minimum requirements
The following are the supported versions and features and the approximate memory and disk space
requirements.
Supported Versions
• The latest version of https://platform.axway.com

Memory
• Approximately 2 MB
Disk space
Supported features
• Persistent storage in Axway's MBS

• Full CRUD operations on custom objects via Models
Installation
To install the MBS connector, execute the following command:
npm install --no-optional @axway/api-builder-plugin-dc-mbs
A configuration file is generated for you and placed into the /conf directory of your API Builder project.
Configuration
Once the plugin is installed, the configuration file is located in <project>/conf/mbs.default.js.
Option name Type Description Required
connector string Must be set to Yes

@axway/api-
builder-plugin-dc-
mbs
username string The user with which to Yes

connect to MBS.
password string The user's password Yes

with which to connect to
MBS.
key string The MBS instance App Yes

Key.
baseurl string The No

location where MBS is h
osted. Defaults to Ampli
fy Platform Production.
pingInterval number The time in ms to ping No

MBS to keep the current
session alive. Defaults t
o once a day. Set to -1 to
disable.

Provisioning an MBS database in the AMPLIFY Platform

1. Follow this guide to provision an MBS database and get a username, password, and app key.
2. From within an API Builder 4.x project, install the connector:
$ npm install --no-optional @axway/api-builder-plugin-dc-mbs
After the successful installation of the connector, a mbs.default.js configuration file will be
automatically created in your project's /conf directory.
After the successful installation of the connector, a configuration file 'mbs.default.js' will be automatically created in your project's c
We recommend providing the app key, username, and password as environment variables. `MBS_KEY`,
`MBS_USER`, and
`MBS_PASSWORD` are the default environment variables used to configure this connector. See
Environmentalization for more information.
After configuring the connector, you can start the service as normal.
Usage
After you configure the connector, you can start up your API Builder project and visit the console (normally
found under http://localhost:8080/console). Your MBS custom object collections will be listed on
the Models tab of the console. However, initially, you will not have any Models from MBS.
Create a Model for MBS
Go to the Models tab and click the + Model button:
In the New Model dialog, change the Connector to "mbs". This indicates that data for this model will be
persisted in MBS.
Refer to the documentation for more information about creating Models.

Known issues and limitations

For a list of known issues and limitations, refer to the API Builder Release Notes.
Mongo Connector
The Mongo data connector is a plugin for API Builder that can connect to your Mongo database instance
and interrogate your schema. It will automatically provision Models into your application, and optionally,
automatically generate a rich CRUD API to the underlying tables. The Models can be used programmatically,
or they can be used within the flow editor to interact with your database.
requirements.
Supported Versions
• MongoDB 3.6
Memory
Disk space
Supported features
• Automatic generation of Models from Mongo collections

• Automatic generation of API for Models
• Full CRUD operations on tables via Models
• Dynamic creation of Model tables
Installation
To install the Mongo connector, execute the following command:
npm install --no-optional @axway/api-builder-plugin-dc-mongo
A configuration file is generated for you and placed into the /conf directory of your API Builder project. By
default, we use a host of localhost and a table called apibuilder.
Configuration
Once the plugin is installed, the configuration file is located in <project>/conf/mongo.default.conf.
Option name Type Description
connector string Must be: @axway/api-

builder-plugin-dc-mongo

url string The MongoDB database URL. For

additional MongoDB database
URL configuration information,
refer to Connection String URI
Format.
generateModelsFromSchema boolean If enabled, API Builder will

automatically interrogate the
database and auto-generate
Models from MongoDB
collections. API Builder
determines the schema for the
auto-generated models by
sampling the collection. If the
collection is empty, the schema
cannot be determined, and the
model will not be generated. This
will cause issues if there are
Flows or APIs, depending on the
model schema.
modelAutogen boolean If enabled, API Builder will

automatically generate a full and
rich CRUD API from the
generated Models.
Usage
found under http://localhost:8080/console ). Your MongoDB collections will be listed on the Models tab of
the console. Now, you can click on the Gear icon to the right of the table names to generate flow-based
APIs.
You can also reference the connector in a custom model.
var User = APIBuilder.Model.extend('user', {

fields: {
name: { type: String, required: false, validator: /[a-zA-Z]{3,}/ }
},
connector: 'mongo'
});
If you want to map a specific model to a specific collection name, use metadata. For example, to map the
user model to the users collection set it as:
var User = APIBuilder.Model.extend('user', {

fields: {
name: { type: String, required: false, validator: /[a-zA-Z]{3,}/ }
},
connector: 'mongo',
metadata: {
'mongo': {
collection: 'users'

}
}
});

MSSQL Connector
The Microsoft SQL Server data connector is a plugin for API Builder that can connect to your MSSQL
instance and interrogate your schema that will automatically provision Models into your project, and
optionally, automatically generate a rich CRUD API to the underlying tables. The Models can be used
programmatically or can be used within the flow editor to interact with your database.
requirements.
Supported Versions
• SQL Server 2008 or later
Memory
Disk space
Supported features
• Automatic generation of Models from SQL tables

Installation
To install the MSSQL connector, execute the following command:
npm install --no-optional @axway/api-builder-plugin-dc-mssql
default, we use a host of localhost, and expect user and password to come from the OS host
environment.
Configuration
Once the plugin is installed, the configuration file is located in <project>/conf/mssql.default.js.


builder-plugin-dc-mssql
user string The user with which to connect to

the database.
password string The user's password with which

to connect to the database.
host string The database host.
port number The database post.
database string The database instance name.
connectionTimeout number Connection timeout in MS
requestTimeout number Request timeout in MS

Models from SQL tables.

generated Models.
options object MSSQL Connection options
options.encrypt boolean Encrypt the database connection.

Required when connecting to
Azure.
Usage
found under http://localhost:8080/console ). Your database tables will be listed on the Models tab of the
console. Now, you can click on the Gear icon to the right of the table names and generate flow-based APIs.
const Account = APIBuilder.Model.extend('Account', {

fields: {
Name: { type: String, required: true }
},
connector: 'mssql'
});

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: 'mssql',
metadata: {
'mssql': {
table: 'accounts'
}
}
});

MySQL Connector
The MySQL data connector is a plugin for API Builder that can connect to your MySQL database instance
and interrogate your schema. It will automatically provision Models into your application, and optionally,
requirements.
Supported Versions
• MySQL 5.7
Memory
Disk space
Supported features

• Connection pooling

Installation
To install the MySQL connector, execute the following command:
npm install --no-optional @axway/api-builder-plugin-dc-mysql
default, we use a host of localhost, and expect user and password to come from the OS host
environment.
Configuration
Once the plugin is installed, the configuration file is located in <project>/conf/mysql.default.js.

builder-plugin-dc-mysql
connectionPooling boolean Enables connection pooling for

better performance and
scalability.
connectionLimit number The number of simultaneous

connections when
connectionPooling is
enabled.
host string The database host.
port number The database port.
database string The database instance name.

the database.



generated Models.
The mysql library used by this connector depends on the MySQL server setting NO_BACKSLASH_ESCAPES
to mitigate against SQL injection attacks. The setting must be disabled (which is the default setting for
MySQL servers).

Usage

fields: {
},
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:

fields: {
},
connector: 'mysql',
metadata: {
'mysql': {
table: 'accounts'
}
}
});

The following are the MySQL connector known issues and limitations:
• Only supports SQL tables.
For a list of additional known issues and limitations, refer to the API Builder Release Notes.
Oracle Connector
The Oracle connector is a plugin for API Builder that can connect to your Oracle database instance and
interrogate your schema. It will automatically provision Models into your application, and optionally,
The following are the supported versions, features, and prerequisites and the approximate memory and disk
space requirements.
Supported Versions
• Oracle 12c

Underlying Driver Version
• The underlying driver used is node-oracledb version 4.0 - supporting Node.js versions 8.16, 10.16, 12,
or later.
Memory
Disk space
Supported features
Prerequisites
This connector requires Oracle Instant Client installed. To install it, please follow the instructions for your
environment here: Oracle Instant Client
The connector also depends on the node-oracledb module. To properly install the connector, please
check the prerequisites here: node-oracledb
Installation
To install the Oracle connector, execute the following command:
npm install --no-optional @axway/api-builder-plugin-dc-oracle
A configuration file is generated for you and placed into the /conf directory of your API Builder project. You
should configure this file before starting your service.
Configuration
Once the plugin is installed, the configuration file is located in <project>/conf/oracle.default.js.

builder-plugin-dc-oracle
connectString string The database instance

connection string. For example:
localhost/orcl

the database.




generated Models.
connectionPooling boolean Enables connection pooling for

better performance, scalability,
and resilience. See the
Connection pooling for more
information. Default: false
poolMax integer The maximum number of

connections to which a
connection pool can grow.
Default: 4
poolMin integer The minimum number of

connections a connection pool
maintains, even when there is no
activity to the target database.
Default: 0
poolPingInterval integer The number of seconds that a

connection has been idle before
it is "pinged" to check the
connection is alive. Default: 60
poolTimeout integer The number of seconds after

which idle connections (unused
in the pool) are terminated.
Default: 60
poolIncrement integer The number of connections that

are opened whenever a
connection request exceeds the
number of currently open
connections. Default: 1
Usage


fields: {
},
connector: 'oracle'
});

fields: {
},
connector: 'oracle',
metadata: {
oracle: {
table: 'accounts'
}
}
});

The following are the Oracle connector known issues and limitation:
• Only supports SQL tables.
For a list of additional known issues and limitations, refer to the API Builder Release Notes.
API Builder Credentials

A credential can be used to grant your service authorization to connect to another service from within flows.
This section describes how to configure credentials in API Builder and how API Builder manages those
credentials.
• Configuring Credentials
• API Key credentials
• HTTP Basic credentials
• OAuth 2.0 credentials
• Environmentalizing Credentials
• Managing Credentials
• Authorization in Swagger Plugin
For additional credential management information, refer to API Builder Standalone credential management.
For how-to information on accessing Gmail using a Swagger flow-node, refer to Access Gmail using a
Swagger flow-node. For how-to information on accessing Microsoft OneDrive using a REST flow-node, refer
to Access Microsoft OneDrive using a REST flow-node.

Configuring Credentials
API Builder credentials are defined in the configuration under the authorization key. Credentials are
uniquely identified by its credential name, and its type. The credential name is how the credential
will be referenced from the flows that use the credential. Each type of credential also requires additional
type-specific configuration information. API Builder supports three credential types, API Key, HTTP Basic,
and OAuth 2.0 with the respective types apiKey, basic, and oauth2.
default.js
authorization: {
credentials: {
"<credential name>": {
type: "<type>",
...
}
}
}
API Key credentials

The apiKey credential type allows you to configure a credential with a static token that will be used as the
value of the credential.
API Key
...,
authorization: {
credentials: {
type: "apiKey",
key: "<token>"
}
}
},
...
Generally, services that require an API key credential have a sign-up page and will grant you an API key once
you have registered. These API keys typically don't expire and can be used in perpetuity.
For example, you have signed up for a weather service, received an API key aaaa-bbbb-1234, and are
aliasing the API key as My Weather. To configure this credential for use in API Builder, your config would
look like this:
default.js
...,
authorization: {

credentials: {
"My Weather": {
type: "apiKey",
key: "aaaa-bbbb-1234"
}
}
},
...
HTTP Basic credentials

The basic credential type allows you to configure a credential with a username and password. The value of
this credential is the Base64 encoded username:password, suitable for use in an HTTP Basic
authorization header, though it does not have the "Basic" prefix embedded. Plugins, such as the Swagger
plugin, that consume the credential will prefix it if necessary.
default.js
authorization: {
credentials: {
type: "basic",
username: "<username>",
password: "<password>"
}
}
}
A common use case for this credential type is connections between API Builder services. At first, it may be a
bit confusing, API Builder has a configuration key called apikey, but the default authentication for an API
Builder service is basic, and the apikey is passed as the username of a basic authentication token. So, if
your service is connected to another API Builder service whose apikey is abcd-1234, your credential
configuration would look like this:
default.js
authorization: {
credentials: {
"API Builder service": {
type: "basic",
username: "abcd-1234",
password: ""
}
}
OAuth 2.0 credentials

Overview
Services that use OAuth 2.0 authorization require that requests present an access_token to prove they
can access the resources they are requesting. For security reasons, these access tokens are often short-
lived, expiry times of 1 hour are common. This presents an issue to services that are trying to consume the

resources; after an hour, the access token expires, preventing access to the resources. This makes the use
of a static credential like API Key or HTTP Basic infeasible.
API Builder solves this by managing the refresh of access tokens and ensuring that there is always a valid
access token available for use within the flows. To achieve this, API Builder performs a refresh token
grant before the expiration of the access token to ensure it always has a valid access token.
Configuration
Each third-party service you are accessing will have their own policies and processes for enabling and
configuring OAuth support. For API Builder to be able to connect to the third-party service and obtain and
manage tokens, it uses the following:
Key Description
flow This is the OAuth flow required for this credential.

Currently, the only supported flow is accessCode.
authentication_url This is the URL of the authorization endpoint. If API

Builder does not have a refresh_token configured
and the authentication URL has been specified,
then you can perform an initial token grant to get
the initial access token.
token_url This is the URL of the token endpoint. API Builder

will call this endpoint to redeem an authorization
code or refresh token and retrieve a new access
token.
client_id This is the OAuth application ID as configured in the

third party service.
client_secret This is the OAuth application secret as configured

in the third party service.
scope The space-separated list of OAuth scopes for which

authorization is requested.
redirect_uri This is an override to allow customizing the redirect

URI for the credential. When performing an
authorization code grant, this is the URI that the
authorization server will redirect to with the
authorization code. In general, the default value
should be sufficient, and there will be no need to set
this.
Default: http://localhost:8080/auth/
callback
access_token Although most services provide short-lived access

tokens, there are a few exceptions that supply long-
lived access tokens.

When deploying to production, there will be no user

interaction to authorize manually. Instead, the pre-
obtained tokens should be provided.
refresh_token This is the refresh token that API Builder will use to
ensure that it always has a valid access token.
When deploying to production, there will be no user
interaction to authorize manually. Instead, the pre-
obtained tokens should be provided.
Depending on the deployment scenario, not all settings may be required, but any setting that is not required
must be set to null. The following is an example configuration for a credential that is accessing Google's
Gmail API:
default.js
authorization: {
credentials: {
mygmail: {
type: 'oauth2',
flow: 'accessCode',
authentication_url: 'https://accounts.google.com/o/
oauth2/v2/auth?access_type=offline&prompt=consent',
token_url: 'https://accounts.google.com/o/oauth2/
token',
client_id: 'myid.apps.googleusercontent.com',
client_secret: 'mysecret',
scope: 'https://mail.google.com/',
access_token: null,
refresh_token: null
}
}
}
Many services will not issue a refresh token by default, consult your service providers OAuth documentation
for information on how to ensure that a refresh token is issued. Generally, it requires custom query
parameters on the authentication URL or a custom scope setting. In this example case, the
authentication_url has access_type=offline&prompt=consent, which tells Google to issue a
refresh token.
Configuring the Redirect URI
When configuring your external service to support OAuth, it will request a redirect URI. After the user has
authorized API Builder access, this is the URI to which the browser is redirected with the authorization code.
Where you configure this in your OAuth application is highly dependent on the service provider you're using.
For example, if you are creating a Microsoft Application (https://apps.dev.microsoft.com), it is configured as
a Platform setting.

If you're configuring a Google Application (https://console.developers.google.com), it is configured under

the Restrictions.
The default Redirect URL for API Builder is http://localhost:8080/auth/callback .
As this is the URL that the user's browser will be redirected to after they perform the authorization in the
popup window, it is important to note that the Redirect URI is relative to the browser from which the
authorization is performed. So by default, authorization will only work when your browser is running on the
same host as the API Builder service.
There may be scenarios where the default localhost Redirect URI is not sufficient for access
requirements; for example, if the developer is working on a machine that is remote to the API Builder
service. The default Redirect URL is generated from the configuration values of baseurl, port, and
authorization.callback. Alternatively, the redirect_uri can be set explicitly on each credential in the
configuration.
However, be aware that most services require the use of HTTPs when the Redirect URI is something other
than localhost. For more information on enabling HTTPs in API Builder, see Enable a secure HTTPS
listener.

Managing token refresh schedule
As mentioned previously, API Builder solves the problem of expiring access tokens by refreshing them
before expiration. The default behavior is for API Builder to refresh the access token on startup and then to
continually refresh the access token 1 minute before the access token's expiration. The default behavior
should be sufficient for the majority of scenarios; however, finer-grained control over the refresh schedule is
available by adjusting the refresh settings in the credential configuration.
Name Value Description
refreshPolicy beforeexpiry This is the default refresh

behavior, API Builder will begin
attempting to refresh the access
token a configured number of
seconds (refreshOffset)
before the token expiry.
onexpiry Some services may not allow

refresh before token expiry. API
Builder will only begin attempting
to refresh the access token once
it has expired. This may mean
there is a window where API
Builder does not have an access
token for the credential.
periodic Periodic refresh tells API Builder

to refresh the access token on a
fixed interval (refreshPeriod),
independent of the token's
expiration.
refreshOffest number Set the seconds before token

expiry (beforeexpiry) to
perform the token refresh.
Default: 60 seconds
refreshPeriod number Set the periodic interval

(periodic) between token
refreshes. Default: 3600 seconds
API Builder Initial Token Grant

A common scenario that you may encounter is where you have the configuration information but no access
or refresh tokens. This can happen as a result of you manually configuring a credential or when you install a
Swagger document, which creates a default credential configuration. In this case, if the service supports
the authorization code grant, it is possible to perform authorization from the API Builder Console UI to get
the initial access token and refresh token.

Warning: Tokens issued in this manner are not persisted and so this only suitable for use during
development. When deploying to production, the tokens should be provided as environmentalized
values.
In the above screenshot, the Gmail App credential and the My Onedrive credential are both OAuth 2.0
credentials that have not been authorized. Click Authorize to start the authorization process.
Once authorization is completed, the status of the credential will be updated, and the credential will be
available for use in a flow.

If the service supports refresh, and the credential is configured to request a refresh token, API Builder will
keep the access token valid by refreshing it before its expiry. However, these tokens are not persistent, and
if API Builder is restarted, the authorization process will need to be repeated. This makes this Initial Token
Grant approach only suitable for development; once in production, the tokens need to be environmentalized.
For more information, see Environmentalizing Credentials.
Environmentalizing Credentials
Overview
Environmentalizing the configuration variables allows you to tailor the API Builder configuration to the
environment it is being deployed to at deployment time. Additionally, environmentalizing the credentials also
ensures their security. Credentials, by their very nature, contain sensitive information that you do not want to
expose by committing them to your source control management (SCM). Credentials may also contain time-
sensitive information, such as OAuth 2.0 access tokens.
Configuring Credentials
The credential configuration uses the same approach for environmentalization as the rest of the API Builder
configuration; any value can be read from an environment variable on startup by replacing it
with process.env.VAR_NAME.

If API Builder is running in a containerized environment, these environment variables are passed into the
container on startup. For information on containerizing an API Builder application, see Dockerize an API
Builder Service.
API Key
For API Key credentials, you should environmentalize the key variable. For example, the key is read from
the environment variable WEATHER_KEY on startup:
default.js
...,
authorization: {
credentials: {
"My Weather": {
type: "apiKey",
key: process.env.WEATHER_KEY
}
}
},
...
HTTP Basic
For HTTP Basic credentials, you should environmentalize the username and password variables. For
example, the username and password are read from the environment variables SERVICE_USER and
SERVICE_PASS respectively on startup:
default.js
authorization: {
credentials: {
"API Builder service": {
type: "basic",
username: process.env.SERVICE_USER,
password: process.env.SERVICE_PASS
}
}
OAuth 2.0
OAuth 2.0 credentials contain both sensitive information and time-sensitive information. In most cases, you
should environmentalize the client_id, client_secret, refresh_token, and access_token.
default.js
authorization: {
credentials: {
gmail: {
type: 'oauth2',
flow: 'accessCode',
authentication_url: 'https://accounts.google.com/o/oauth2/v2/auth?
access_type=offline&prompt=consent',
token_url: 'https://accounts.google.com/o/oauth2/token',
client_id: process.env.GMAIL_CLIENT_ID,
client_secret: process.env.GMAIL_CLIENT_SECRET,
scope: 'https://mail.google.com/',
access_token: process.env.GMAIL_ACCESS_TOKEN || null,

refresh_token: process.env.GMAIL_REFRESH_TOKEN || null

}
}
}
The || null on the access_token and refresh_token is not required, but if it is omitted, you must
have set the environment variables. With the || null included, API Builder will start, and while developing,
you can perform the initial token grant in the Admin Console UI.
Managing Credentials
Credentials are used to grant your API Builder service authorization to connect to another service. On
the Credentials tab, you will see a card view listing of all the currently configured credentials.
Each card displays useful information about the credential.

Credential Name The credential name is the value that is used in the
flows to access this credentials tokens.
Credential Type The type of the credential - API Key, HTTP Basic or
OAuth 2.0
Credential Actions The actions that can be performed on this

credential. These will depend on the type of the
credential and also on the status of the credential.
For example, in the case where the credential is an
OAuth 2.0 credential, but there is no access token,
there will be an Authorize action that will perform
the initial token grant in the UI. For more
information see OAuth 2.0 credentials.
Status Text This is a text description of the status of the

credential.
Status Icon Icon to indicate the status of the credential.
Credentials Notifications
When invalid credentials exist in your service, a red notification badge is displayed on the Credentials tab. It
shows the total number of invalid credentials plus those that require authorization:
An amber badge is shown when there are no invalid credentials, but there are existing OAuth2 credentials
that need to be authorized:

Authorization in Swagger Plugin

Overview
By default, API Builder projects install the Swagger plugin - @axway/api-builder-plugin-fn-
swagger. API Builder supports the OpenAPI/Swagger 2.0 specification, and the Swagger plugin creates
flow-nodes that allow API Builder to interact with the services described in the Swagger documents. For
more information, see Swagger flow-node.
In OpenAPI/Swagger 2.0, the security mechanisms supported by the API are defined in a Security Definitions
Object. API Builder uses this configuration information to create credential stubs to make getting started
with authorized APIs easier.
Swagger generated credentials

The Swagger plugin assists in creating managed credentials. When API Builder loads new Swagger
documents with securityDefinitions which have been placed in the ./swagger directory, it will
generate a configuration file for that Swagger service. For example, if API Builder loaded the Swagger
document swagger/onedrive.json, it would generate a configuration file conf/
onedrive.default.js. This generated configuration will contain stub credentials suitable for accessing
the Swagger service. These stub credentials are incomplete and contain null values where the application-
specific information needs to be supplied.
The following security definitions are supported when generating stub credentials:
• HTTP Basic
• API Key
• OAuth 2.0 (only accessCode grant flow)
Any Swagger documents using any other OAuth 2.0 grant flows (for example implicit, password, and
application) are not supported and will throw an exception on startup when the credential gets generated.
API Key
Swagger security definitions of type apiKey will generate an API Key credential. For example, given a
Swagger document:

swagger/myswagger.json
"info": {
...,
"title": "My Swagger",
...
},
...,
"securityDefinitions": {
"api_key": {
"type": "apiKey",
"name": "api_key",
"in": "header"
},
},
...
The Swagger plugin will generate a configuration file with the credential:
conf/myswagger.default.js
...,
authorization: {
credentials: {
'My Swagger api_key': {
type: 'apiKey',
key: null
}
}
}
...
Before this credential can be used in a flow, the key will need to be set.
HTTP Basic
Swagger security definitions of type basic will generate an HTTP Basic credential. For example, given a
Swagger document:
swagger/myswagger.json
"info": {
...,
...
},
...,
"basic_cred": {
"type": "basic"
},
},
...

...,
authorization: {
credentials: {
'My Swagger basic_cred': {
type: 'basic',
username: null,
password: null
}
}
}
...
Before this credential can be used in a flow, both the username and the password must be set. If there is
not a password or a username, set the value to an empty string, for example:
...,
authorization: {
credentials: {
'My Swagger basic_cred': {
type: 'basic',
username: 'I have no password',
password: ''
}
}
}
...
OAuth 2.0
Swagger security definitions of type oauth2 will generate an OAuth 2.0 credential. For example, given a
Swagger document:
swagger/myswagger.json Expand source

"info": {
...,
...
},
...,
"Oauth2": {
"authorizationUrl": "https://accounts.google.com/o/oauth2/auth",
"tokenUrl": "https://accounts.google.com/o/oauth2/token",
"description": "Oauth 2.0 authentication",
"flow": "accessCode",
"scopes": {
"https://mail.google.com/": "Read, send, delete, and manage your
email",
"https://www.googleapis.com/auth/gmail.compose": "Manage drafts and
send emails",
"https://www.googleapis.com/auth/gmail.insert": "Insert mail into your
mailbox",

"https://www.googleapis.com/auth/gmail.labels": "Manage mailbox

labels",
"https://www.googleapis.com/auth/gmail.metadata": "View your email
message metadata such as labels and headers, but not the email body",
"https://www.googleapis.com/auth/gmail.modify": "View and modify but
not delete your email",
"https://www.googleapis.com/auth/gmail.readonly": "View your email
messages and settings",
"https://www.googleapis.com/auth/gmail.send": "Send email on your
behalf",
"https://www.googleapis.com/auth/gmail.settings.basic": "Manage your
basic mail settings",
"https://www.googleapis.com/auth/gmail.settings.sharing": "Manage your
sensitive mail settings, including who can manage your mail"
},
"type": "oauth2"
}
},
...
...,
authorization: {
credentials: {
'Gmail Oauth2': {
type: 'oauth2',
flow: 'accessCode',
authentication_url: 'https://
accounts.google.com/o/oauth2/auth',
token_url: 'https://accounts.google.com/o/
oauth2/token',
scope: 'https://mail.google.com/ https://
www.googleapis.com/auth/gmail.compose https://www.googleapis.com/auth/
gmail.insert https://www.googleapis.com/auth/gmail.labels https://
www.googleapis.com/auth/gmail.modify https://www.googleapis.com/auth/
gmail.readonly https://www.googleapis.com/auth/gmail.send https://
www.googleapis.com/auth/gmail.settings.basic https://www.googleapis.com/auth/
gmail.settings.sharing',
client_id: null,
client_secret: null,
access_token: null,
refresh_token: null
}
}
}
...
Before this credential can be used in a development environment the client_id and client_secret
must be set. This will allow API Builder to perform an initial token grant in the Admin Console UI. For more
information, see OAuth 2.0 credentials.

As discussed in the OAuth 2.0 credentials page, access tokens are generally short-lived, which makes using
them in production environments problematic as they will expire soon after being deployed. To alleviate this,
API Builder manages the OAuth 2.0 credentials and will perform refresh grants to ensure their access
tokens never expire. For this to be possible, the credential needs to be configured to request a refresh token.
This is generally referred to as requesting offline access. However, how it is done is not standardized; some
providers (like Google) require URL parameters while others may require specific scopes (like Microsoft's
Graph API). It is unlikely that your Swagger document is going to have this pre-configured, and you will need
to consult your service provider's documentation before updating the credential.
For example, requesting a refresh token for Google requires you to set an access_type and prompt on
the authentication_url. For more information, see Google's Using OAuth 2.0 for Web Server
Applications.
...,
authorization: {
credentials: {
'Gmail Oauth2': {
...,
authentication_url: 'https://
accounts.google.com/o/oauth2/v2/auth?access_type=offline&prompt=consent',
...
}
}
}
...
This approach works great in development, allowing you to manage authorization via the Admin Console UI.
However, to take this to a production environment where there is no Admin Console, you also need to set
the access_token and refresh_token in the credential. For more information, see Environmentalizing
Credentials.
API Builder Flows

Introduction
You can manage endpoints and their associated flows using the API Builder Console. You can also create
and edit flows and configure their associated flow-nodes using the API Orchestration user interface.
Manage endpoints
An API endpoint provides a way for a client to access your application, such as GET
<SERVER_ADDRESS>/api/users/query, and access the application's models and custom code blocks
to return data to the client application. You can use the API Builder Console to import, generate, export, and
delete endpoints. For additional information, refer to Manage Endpoints.
Manage flows
Flows are acyclic directed graphs of operational flow-nodes, which are composed of inputs, logic, and
outputs. They are used by endpoints, which require them for their runtime functionality of taking inputs and
turning them into responses when an endpoint is hit. You can use the API Builder Console and the

associated API Orchestration user interface to view, create, and edit flows. For additional information, refer
to Manage Flows. For how-to examples of configuring flows, refer to Flow Examples.
Manage flow-nodes
Flow-nodes represent an individual portion of functionality in a flow. You can use the API Orchestration user
interface to add, configure, and delete flow-nodes. You can also connect and disconnect flow-nodes in a
flow. For additional information, refer to Manage flow-nodes.
Flow-nodes
Flows can be viewed and edited on the API Orchestration user interface. Additionally, you can manage flow-
node configuration and connections on the API Orchestration user interface. For flow-node
configuration reference information, refer to Flow-nodes.
Axway Flow SDK

The Axway Flow SDK (axway-flow-sdk) is a standalone utility that enables the creation of custom flow
flow-nodes for API Builder flows. For additional information, refer to Axway Flow SDK.
Manage Endpoints
An API endpoint provides a way for a client to access your application, such as GET
<SERVER_ADDRESS>/api/users/query, and access the application's models and custom code blocks
to return data to the client application. To create API endpoints, see the API reference or follow the Generate
endpoints instructions. For reference information on flow orchestration and flow-node configuration, refer to
Flow-nodes.
Import endpoints
Warning: A Swagger API endpoint definition file can only be imported once. If you attempt to import a
Swagger file for the same API endpoint definition, you will receive a server error message due to
conflicting paths.
When designing API to import, you should refer to the apiPrefix section in Project Configuration for
important API design considerations.
To import API endpoints using the API Builder user interface:
1. Select the API Doc & Test tab.

2. Click the + API button on the right side. The Import API Definition page is displayed.
3. Select a file from your local file system or enter a URL. A file can be selected by browsing or dragging
and dropping it. The selected file must be a Swagger formatted JSON or YAML file. Once a file is
selected, or a URL entered, the API summary review page is displayed.
4. Click the Save button on the right to import and save the selected API endpoint. Click the Save and
mock button to save and mock the selected API endpoint. You can mock imported APIs to get early
feedback from your API consumers and reduce your overall time-to-market. Click the Cancel button to
cancel the import of the selected API endpoint. When the Save button or the Save and mock button is
clicked, the server will restart. Once the server restart is completed, the imported API endpoints will be
displayed on the APIs List page. The imported API endpoints will be disabled, and each will have a
Create Flow and Delete icons. To create the API endpoint flows, refer to the Create flows instructions
in Manage Flows.
Generate endpoints
API Builder may auto-generate APIs for certain models. These APIs are hard-coded and cannot be used with
flows or the orchestration flow editor.

To generate endpoints that have flows that can be edited within the flow editor using the API Builder user
interface:
1. Select the Models tab.

2. Click the Gear icon.
3. Select Generate endpoints. The previously generated Endpoints will be overwritten caution window is
displayed.
4. Select Proceed to generate the model endpoint flows. Select Cancel endpoint generation to return to
the Models tab.
5. If Proceed is selected, the new endpoints will be generated, and the server will be restarted. Once the
endpoints are generated, the Endpoint has been generated success window is displayed.
6. To view and manage the Endpoints, select Go to API details. The method, path, nickname, description,
and status (enabled, disabled, or error) of each generated endpoint is provided on the APIs List page.
Additionally, Flow and Delete icons are provided for each Endpoint.
Export endpoints
To export an API endpoint as a Swagger file using the API Builder user interface:

2. Select the API endpoint to export from the API Endpoints list. Selecting the API endpoint to export will
open the APIs List page.
3. Click the Download Swagger button to download the selected API endpoint as a Swagger file in the
original format that it was imported (for example, JSON or YAML).
4. Select the file download location on your file system.
5. Confirm the file download.
Delete endpoints
To delete endpoints using the API Builder user interface:

2. Select the API endpoint to manage from the API Endpoints list. Selecting the API endpoint to manage
will open the APIs List page.

3. Select the Delete icon for the endpoint to delete. The Endpoint delete caution window is displayed.
4. Select Proceed to delete the selected endpoint. Select Cancel to return to the API List page. If Proceed
is selected, the endpoint and any associated flow are deleted, and the server is restarted. Once the
server restart is completed, the APIs List page is displayed.
Manage Flows
Flows are acyclic directed graphs of operational flow-nodes, which are composed of inputs, logic, and
outputs. They are used by endpoints, which require them for their runtime functionality of taking inputs and
turning them into responses when an endpoint is hit. For reference information on flow orchestration and
flow-node configuration, refer to Flow-nodes.
Add API endpoints

To import and add API endpoints and flows, refer to Manage Endpoints.
View flows
To view a flow using the API Builder user interface:

2. Select an API Endpoint to view the API List of endpoints. The API Lists page is displayed. Endpoints
that are flow-based have a Flow icon displayed. Endpoints that are programmatically-based do not
have a Flow icon display. Additionally, the method, path, nickname, description, and status of each
endpoint is provided on the APIs List page.
3. Select the Flow icon for the endpoint flow you want to view. The selected flow is displayed in the flow
editor panel on the API Orchestration user interface.
4. To exit the API Orchestration user interface and return to the API Lists page, select Close.
Create flows
To create a flow using the API Builder user interface:
1. Import an API endpoint per the Add endpoints instructions in Manage Endpoints. Once the API
endpoints are imported, and the server is restarted, the imported API endpoints are displayed on the
APIs List page. The imported API endpoints are disabled, and each endpoint has Create Flow and
Delete icons. Additionally, the method, path, nickname, description, and status of each imported
endpoint is provided on the APIs List page.
2. Click the Create Flow icon for an endpoint. The API Orchestration user interface is displayed, and a
Start flow-node is presented in the flow editor panel.
3. Add flow-nodes to the flow. Refer to the Add flow-node instructions in Manage flow-nodes.
4. Configure the flow-nodes added to the flow. Refer to the Configure flow-node instructions in Manage
flow-nodes.

5. Connect the flow-nodes in the flow. Refer to the Connect flow-nodes instructions in Manage Flows.
6. When the flow is complete, click the Apply button. The Flow save caution window is displayed.
Warning: Only changes to valid flows can be applied.
7. Select Proceed to save the flow. Select Cancel to return to the API Orchestration user interface. If
Proceed is selected, the server is restarted, and the flow is saved. Once the server restart is
completed, the API Orchestration user interface is displayed, and the flow is enabled. For flow creation
examples, refer to Flow Examples.
8. To exit the API Orchestration user interface and return to the API Lists page, select Close. If you select
Close and there are unsaved changes to the flow, the Close caution window is displayed.
9. Select Save and exit to save the flow changes and return to the API Lists page. Select Discard
changes to discard the unsaved changes to the flow and return to the API Lists page.
Edit flows
To edit a flow using the API Builder user interface:

2. Select an API Endpoint to view the API List of endpoints. The API Lists page is displayed.
3. Select the Flow icon for the API endpoint flow to edit. The selected flow is displayed in the flow editor
panel on the API Orchestration user interface.
4. Make the required edits to the flow. For instructions on adding, configuring, and connecting flow-nodes
or disconnecting and deleting flow-nodes, refer to Manage flow-nodes.

5. Once the flow edits are completed, click the Apply button. The Flow save caution window is displayed.
6. Select Proceed to save the flow. Select Cancel to return to the API Orchestration user interface. If
Proceed is selected, the server is restarted, and the flow is saved. Once the server restart is
completed, the API Orchestration user interface is displayed.
7. To exit the API Orchestration user interface and return to the API Lists page, select Close. If you
select Close and there are unsaved changes to the flow, the Close caution window is displayed.
8. Select Save and exit to save the flow changes and return to the API Lists page. Select Discard
changes to discard the unsaved changes to the flow and return to the API Lists page.
Debug a flow
Beginning with the Osaka release of API Builder Standalone, the ability for Flows to be provided with
parameters and executed without having to leave the Flow Editor has been added. For additional
information and to get started using the Flow Editor debug feature, refer to Debug a flow.
Delete endpoints
To delete an endpoint using the API Builder user interface:

2. Select an API Endpoint to view the API List of endpoints. The API Lists page is displayed.
3. Select the Delete icon for the API endpoint to delete. The Endpoint delete caution window is displayed.

4. Select Proceed to delete the selected API endpoint. Select Cancel to return to the APIs List page. If
Proceed is selected, the endpoint and any associated flow are deleted, and the server is restarted.
Once the server restart is completed, the APIs List page is displayed.
Flow Examples
This topic provides examples of using the flow editor on the API Orchestration user interface to create flows
and configure and connect the flow-nodes in the flow. The examples use the Swagger definition import of
the test user service endpoints. For additional information on importing endpoints, refer to the Importing
endpoints section of Manage Endpoints. The following flow examples are provided:
• Count Users
• Create a User
• Delete All Users
• Delete a User
• Find a Distinct User
• Find All Users
• Find and Modify Users
• Find a User by ID
• Query a User
• Update a User
• Upsert a User
Count Users
Count Users
To configure a count users flow:
1. Click the Create Flow icon associated with counting test users.
The API Orchestration user interface is displayed.
2. Select and pull the testuser flow-node onto the flow editor from the Models list. Note that the Start
flow-node is automatically connected to the input of the testuser flow-node.
3. Name the flow-node: Count testusers
4. Select the count method.
5. Select Parameters.
6. Enable the where parameter and begin typing in the parameter field. If selector is selected from the
selector drop-down menu, as you begin typing in the parameter field, a drop-down menu of valid or
previously used selector options is displayed. You may optionally choose a selector from the list, or
continue typing to configure the parameter manually. For additional selector auto-complete
information, refer to Manage flow-nodes. For additional information on the Model flow-node and
General flow-node configuration parameters, refer to Flow-nodes.
7. Select Outputs.
8. Configure the next output. As you begin typing in the next field, a drop-down menu of valid or
previously used output options is displayed. You may optionally choose an output from the list, or
continue typing to configure the parameter manually.
9. Select and pull an HTTP flow-node onto the flow editor from the Core list.
10. Name the flow-node: Count succeeded


12. For the status parameter, select number and enter 200 in the field.
13. Enable the body parameter, select selector, and enter $.count in the field.
14. Leave the headers parameter disabled.
15. Connect the next output of the Count users flow-node to the input of the Count succeeded flow-node.
For additional information on connecting flow-nodes in a flow, refer to Manage flow-nodes. The
completed flow is displayed.
16. Click Apply.

17. On the next screen, click Proceed. The server will be restarted, the Count users flow will be saved and
enabled, and you will be returned to the API Orchestration user interface.
18. To exit API Orchestration user interface and return to API Lists page, click Close.
Create a User
Create a User
To configure a create a user flow:
1. Click the Create Flow icon associated with creating a simple user.
3. Name the flow-node: Create testuser
4. Select the create method.
6. Configure the data parameter. If selector is selected from the selector drop-down menu, as you begin
typing in the data parameter field, a drop-down menu of valid or previously used selector options is
displayed. You may optionally choose a selector from the list, or continue typing to configure the
parameter manually. For additional selector auto-complete information, refer to Manage flow-nodes.
For additional information on the Model flow-node and General flow-node configuration parameters,
refer to Flow-nodes.
7. Select Outputs.

9. Select and pull a JavaScript flow-node onto the flow editor from the Core list. If this is not available,
you can install it following the instructions here.
10. Name the flow-node: Set header location
13. Configure the code parameter. Select Edit Javascript and return an object which contains the location
header.
14. Select Outputs.
16. Configure the error output. As you begin typing in the error field, a drop-down menu of valid or
17. Connect the next output of the Create user flow-node to the input of the Set header location flow-node.
For additional information on connecting flow-nodes in a flow, refer to Manage flow-nodes.
19. Name the flow-node: Create succeeded
22. Leave the body parameter disabled.
23. Enable and configure the headers parameter. If selector is selected from the selector drop-down
menu, as you begin typing in the headers parameter field, a drop-down menu of valid or previously
used selector options is displayed. You may optionally choose a selector from the list, or continue
typing to configure the parameter manually. For additional selector auto-complete information, refer to
Manage flow-nodes. For additional information on the Model flow-node and General flow-node
configuration parameters, refer to Flow-nodes.
25. Name the flow-node: Create failed
28. Leave the body and headers parameters disabled.
29. Connect the next output of the Set header location flow-node to the input of the Create succeeded
flow-node. For additional information on connecting flow-nodes in a flow, refer to Manage flow-nodes.
30. Connect the error output of the Set header location flow-node to the input of the Create failed flow-
node. For additional information on connecting flow-nodes in a flow, refer to Manage flow-nodes. The

31. Click Apply.

32. On the next screen, click Proceed. The server will be restarted, the Create a user flow will be saved and
Delete All Users

Delete All Users
To configure a delete all users flow:
1. Click the Create Flow icon associated with deleting all test users.
3. Name the flow-node: Delete all testusers
4. Select the deleteAll method.
5. Select Outputs.
8. Name the flow-node: Delete succeeded
12. Connect the next output of the Delete all users flow-node to the input of the Delete succeeded flow-

13. Click Apply.

14. On the next screen, click Proceed. The server will be restarted, the Delete all users flow will be saved
and enabled, and you will be returned to the API Orchestration user interface.
Delete a User
Delete a User
To configure a delete a user flow:
1. Click the Create Flow icon associated with deleting a test user.
3. Name the flow-node: Delete testuser
4. Select the delete method.
6. Configure the id parameter. If selector is selected from the selector drop-down menu, as you begin
typing in the id parameter field, a drop-down menu of valid or previously used selector options is
7. Select Outputs.
9. Configure the notfound output. As you begin typing in the notfound field, a drop-down menu of valid or

11. Name the flow-node: Delete succeeded
16. Name the flow-node: Delete failed
20. Connect the next output of the Delete a user flow-node to the input of the Delete succeeded flow-node.
For additional information on connecting flow-nodes in a flow, refer to Manage flow-nodes.
21. Connect the notfound output of the Delete a user flow-node to the input of the User not found flow-
22. Click Apply.

23. On the next screen, click Proceed. The server will be restarted, the Delete a user flow will be saved and
Find All Users

Find All Users
To configure a find all users flow:
1. Click the Create Flow icon associated with finding all test users.
3. Name the flow-node: Find all testusers
4. Select the findAll method.
5. Select Outputs.

8. Name the flow-node: Find succeeded
11. Enable the body parameter, select selector, and select $.models from the selector options drop-
down menu or continue typing to manually complete the selector configuration. For additional selector
auto-complete information, refer to Manage flow-nodes.
13. Connect the next output of the Find all users flow-node to the input of the Find succeeded flow-node.
14. Click Apply.

15. On the next screen, click Proceed. The server will be restarted, the Find all users flow will be saved and
Find a Distinct User

Find a Distinct User
To configure a find a distinct user flow:
1. Click the Create Flow icon associated with finding a distinct test user.
3. Name the flow-node: Find distinct testuser
4. Select the distinct method.

6. Enable all parameters and configure them. If selector is selected from the selector drop-down menu,
as you begin typing in the parameter field, a drop-down menu of valid or previously used selector
options is displayed. You may optionally choose a selector from the list, or continue typing to
configure the parameter manually. For additional selector auto-complete information, refer to Manage
flow-nodes. For additional information on the Model flow-node and General flow-node configuration
parameters, refer to Flow-nodes.
7. Select Outputs.
down menu or continue typing to complete the selector configuration manually. For additional selector
15. Connect the next output of the Find a distinct user flow-node to the input of the Find succeeded flow-
16. Click Apply.

17. On the next screen, click Proceed. The server will be restarted, the Find a distinct user flow will be
saved and enabled, and you will be returned to the API Orchestration user interface.
Find a User by ID
Find a User by ID
To configure a find a user by ID flow:

1. Click the Create Flow icon associated with finding a test user using their ID.
3. Name the flow-node: Find a user by ID
4. Select the findByID method.
6. Configure the id parameter. If selector is selected from the selector drop-down menu, as you begin
typing in the id parameter field, a drop-down menu of valid or previously used selector options is
7. Select Outputs.
14. Enable the body parameter, select selector, and select $.model from the selector options drop-down
menu or continue typing to complete the selector configuration manually. For additional selector auto-
complete information, refer to Manage flow-nodes.
16. Connect the next output of the Find a user by ID flow-node to the input of the Find succeeded flow-
node. For additional information on connecting flow-nodes in a flow, refer to Manage flow-nodes.
18. Name the flow-node: Find failed
22. Connect the notfound output of the Find a user by ID flow-node to the input of the User not found flow-

23. Click Apply.

24. On the next screen, click Proceed. The server will be restarted, the Find a user by ID flow will be saved
Find and Modify Users

Find and Modify Users
To configure a find and modify users flow:
1. Click the Create Flow icon associated with finding and modifying a test user.
2. Select and pull a Set Context flow-node onto the flow editor from the Core list. Note that the Start flow-
node is automatically connected to the input of the Set Context flow-node.
3. Name the flow-node: Build args parameter (new)
5. For the value parameter, select selector and select $.params.new from the selector options drop-
6. Select Outputs.
8. Select and pull a Set Context flow-node onto the flow editor from the Core list.
9. Name the flow-node: Build args parameter (upsert)
11. For the value parameter, select selector and select $.params.upsert from the selector options
drop-down menu or continue typing to complete the selector configuration manually. For additional
selector auto-complete information, refer to Manage flow-nodes.
12. Select Outputs.

14. Connect the next output of the Build args parameter (new) flow-node to the input of the Build args
parameter (upsert) flow-node. For additional information on connecting flow-nodes in a flow, refer
to Manage flow-nodes.
15. Select and pull the testuser flow-node onto the flow editor from the Models list.
16. Name the flow-node: Find and modify testuser
17. Select the findAndModify method.
20. Enable the additional parameters and configure them according to the findAndModify parameters
listed in Flow-nodes.
21. Select Outputs.
24. Connect the next output of the Build args parameter (upsert) to the input of the Find and modify users
flow-node. For additional information on connecting flow-nodes in a flow, refer to Manage flow-nodes.
26. Name the flow-node: Find and modify succeeded
30. Connect the next output of the Find and modify users flow-node to the input of the Find and modify
succeeded flow-node. For additional information on connecting flow-nodes in a flow, refer to Manage
flow-nodes.
32. Name the flow-node: Find and modify failed
36. Connect the notfound output of the Find and modify users flow-node to the input of the Users not
found flow-node. For additional information on connecting flow-nodes in a flow, refer to Manage flow-

nodes. The completed flow is displayed.
37. Click Apply.

38. On the next screen, click Proceed. The server will be restarted, the Find and modify users flow will be
saved and enabled, and you will be returned to the API Orchestration user interface.
Query a User
Query a User
To configure a query a user flow:
1. Click the Create Flow icon associated with querying a test user.
3. Name the flow-node: Query a testuser
4. Select the query method.

6. Enable all parameters and configure them. If selector is selected from the selector drop-down menu,
as you begin typing in the parameter field, a drop-down menu of valid or previously used selector
options is displayed. You may optionally choose a selector from the list, or continue typing to
configure the parameter manually. For additional selector auto-complete information, refer to Manage
flow-nodes. For additional information on the Model flow-node and General flow-node configuration
parameters, refer to Flow-nodes.
7. Select Outputs.
10. Name the flow-node: Query succeeded
down menu or continue typing to manually complete the selector configuration. For additional selector
15. Connect the next output of the Query a user flow-node to the input of the Query succeeded flow-node.
16. Click Apply.

17. On the next screen, click Proceed. The server will be restarted, the Query a user flow will be saved and
Update a User
Update a User
To configure an update a user flow:
1. Click the Create Flow icon associated with updating a test user.
3. Name the flow-node: Update testuser

4. Select the update method.

6. Configure the parameters. If selector is selected from the selector drop-down menu, as you begin
typing in the parameter field, a drop-down menu of valid or previously used selector options is
7. Select Outputs.
11. Name the flow-node: Update succeeded
15. Connect the next output of the Update a user flow-node to the input of the Update succeeded flow-
17. Name the flow-node: Update failed
21. Connect the notfound output of the Update a user flow-node to the input of the User not found flow-
22. Click Apply.

23. On the next screen, click Proceed. The server will be restarted, the Update a user flow will be saved

Upsert a User
Upsert a User
To configure an upsert (update or insert) a user flow:
1. Click the Create Flow icon associated with updating or inserting a test user.
3. Name the flow-node: Upsert testuser
4. Select the upsert method.
6. Configure the value parameter. If selector is selected from the selector drop-down menu, as you begin
typing in the value parameter field, a drop-down menu of valid or previously used selector options is
7. Select Outputs.
8. Configure the update output. As you begin typing in the update field, a drop-down menu of valid or
9. Configure the upsert output. As you begin typing in the upsert field, a drop-down menu of valid or
10. Select and pull a Set Context flow-node onto the flow editor from the Core list.
11. Name the flow-node: Set location
13. For the value parameter, select selector and select $.model.id from the selector options drop-down
menu or continue typing to manually complete the selector configuration. For additional selector auto-
complete information, refer to Manage flow-nodes.
14. Connect the insert output of the Upsert a user flow-node to the input of the Set location flow-node. For
additional information on connecting flow-nodes in a flow, refer to Manage flow-nodes.
16. Name the flow-node: Update succeeded
20. Connect the update output of the Upsert a user flow-node to the input of the Upsert succeeded flow-
22. Name the flow-node: Insert succeeded
25. Leave the body parameter disabled.
26. Enable the headers parameter, select selector, and select $.headers from the selector options drop-
27. Connect the insert output of the Upsert a user flow-node to the input of the Insert succeeded flow-
28. Connect the next output of the Set location flow-node to the input of the Insert succeeded flow-node.

29. Click Apply.

30. On the next screen, click Proceed. The server will be restarted, the Upsert a user flow will be saved and
Manage flow-nodes
This topic describes how to manage flow-nodes and the connections between flow-nodes on the API
Orchestration user interface. The API Orchestration user interface is accessed from the APIs List page on
the API Builder Console by selecting a Flow icon or a Create Flow icon for a generated or imported endpoint
depending upon the current endpoint status. The API Orchestration user interface is divided into the
following panels:
• Flow-node list (left side of the API Orchestration user interface) - Provides a graphical listing of the
Model and Core flow-nodes. The default Core flow-node types are Authorization, Custom, Codeblock,
Condition, Delay, HTTP, JSON, JavaScript, Mustache, and Set Context. A model flow-node is displayed
for each configured model, and an endpoint flow-node is displayed for each imported endpoint. Flow-
node list can be collapsed by clicking the Collapse icon and expanded by clicking the Expand icon.
• Flow editor (center of the API Orchestration user interface) - Provides a graphical space to view, edit,
and create flows.
• Flow-node configuration (right side of the API Orchestration user interface) - Provides the functionality
to configure the Name, Method, Parameters, and Outputs of flow-nodes.
API Orchestration user interface example:

The procedures in this topic appear in the most probable configuration order. To manage API endpoints,
refer to Manage Endpoints. To manage API endpoint flows, refer to Manage Flows.
Add flow-nodes
To add flow-nodes to a flow:
1. Select the flow-node to add to the flow from the listed flow-nodes from the panel on the left.
2. Drag the selected flow-node onto the flow editor panel in the center of the API Orchestration user
interface. The flow-node will automatically align with any additional flow-nodes in the flow. A warning
message may be displayed, and the flow-node may be highlighted until it is configured.
Configure flow-nodes
To configure flow-nodes in a flow:
1. Select a flow-node on the flow editor panel to configure its properties.

2. If necessary, select and change the default flow-node name. Flow-node naming should reflect the
function of the flow-node.
3. Select a Method from the Method drop-down menu. For additional information on the Model and
General flow-node Method selections, refer to Flow-nodes.
4. Select Parameters and complete or edit the parameter configuration entries. If selector is selected
from the selector drop-down menu, as you begin typing in the parameter field, a drop-down menu of
valid or previously used selector options is displayed. You may optionally choose a selector from the
list, or continue typing to configure the parameter manually. For additional selector auto-complete
information, refer to Selector and output auto-complete. Note that the parameter entries are
dependent on the selected flow-node method. For additional information on the Model flow-node and
General flow-node configuration parameters, refer to Flow-nodes.
5. Select Outputs and complete or edit the output configuration entries. As you begin typing in the output
field, a drop-down menu of valid or previously used output options is displayed. You may optionally

choose an output from the list, or continue typing to configure the parameter manually. For additional
information on the Model and General flow-node output configuration for each method, refer to Flow-
nodes. Once the flow-node is properly configured, the warning message is longer displayed, and the
flow-node is longer highlighted.
Selector and output auto-complete
When you edit a selector or an output parameter, any previously used or valid selectors or outputs are
displayed in a context-assisted drop-down menu that shows the selectors or outputs that match the input
text. You may optionally choose a selector or output from the list, or continue typing to configure the
parameter manually.
Authorize flow-nodes with credentials
Warning: This feature requires at least v2.0 of the Swagger plugin.
If authorization is required for a flow-node, then it will contain a drop-down for you to be able to specify
the Credential to use. It requires that you have previously configured Credentials, any that are valid and
ready to be used as authorization parameters in your flows.
Alternatively, credentials can be accessed by name using the Authorization flow-node and provided to flow-
nodes which don't advertise authorization parameters using a selector.
Connect flow-nodes
Warning: All API endpoint flows begin with a default Start flow-node.
Start flow-nodes can only be connected to one other flow-node in the flow. To connect the output of the
Start flow-node to the input of another flow-node:
1. Click on the Start flow-node.

2. While leaving the Start flow-node selected, move your pointer off the Start flow-node. The output
connection on Start flow-node and the input connections on the additional flow-nodes in the flow will
be displayed. The connector from the Start flow-node will follow the movement of the cross-hair of
your pointer.
3. Pull the connector towards the next flow-node to include in the flow. The connector will snap to the
input of the next flow-node to include in the flow when you hover over it.
4. To finish the connection, drop the connector on the input of the next flow-node in the flow. The flow is
automatically rearranged according to the existing connectors and flow-nodes.
To connect the output or outputs of a flow-node to the input of another flow-node:

1. Click on the output of a flow-node to connect to the input of another flow-node.

2. While leaving the output of flow-node selected, move your pointer off the output of the flow-node. The
output connection and the input connections on the additional flow-nodes in the flow that can be
connected will be displayed. The connector from the output of the flow-node will follow the movement
of the cross-hair of your pointer.
3. Pull the connector towards the next flow-node to include in the flow. The connector will snap to the
input of the next flow-node to include in the flow when you hover over it.
4. To finish the connection, drop the connector on the input of the next flow-node in the flow. The flow is
automatically rearranged according to the existing connectors and flow-nodes.
Remove connections between flow-nodes

To remove a connection between flow-nodes:
1. Select the connection to remove.

2. Click the keyboard Del key or Backspace key. The selected connection is removed, and the flow is
automatically rearranged according to the existing connections and flow-nodes.
Remove flow-nodes from flows

To remove a flow-node from a flow:
1. Select the flow-node to remove from the flow.

2. Click the keyboard Del key or Backspace key. The flow-node delete caution screen is displayed.
3. Click Proceed to complete the removal of the selected flow-node and return to the flow. Select Cancel
to cancel the removal of the selected flow-node and return to the flow.
Flow-nodes
This topic describes the flow-nodes available on the API Orchestration user interface as part of the initial
installation of API Builder. The flow-nodes are listed on the left side of the API Orchestration user interface.
The default Core flow-node types are Base64, Codeblock, Compose, Condition, Delay, HTTP, JSON, and Set
Context. The default Connector flow-node is REST. A model flow-node is displayed for each configured
model and an endpoint flow-node is displayed for each imported endpoint. The default Model flow-node is
named testuser.
• Authorization flow-node
• Base64 flow-node
• Codeblock flow-node
• Compose flow-node

• Condition flow-node
• Delay flow-node
• DoT flow-node
• HTTP flow-node
• JavaScript flow-node
• JSON flow-node
• Model flow-nodes
• Mustache flow-node
• REST flow-node
• Set Context flow-node
• Swagger flow-node
Authorization flow-node
The Authorization flow-node can be used to retrieve the value of a known credential by name for use within
the flow, for example, to authorize other services.
The Authorization flow-node methods, parameters, and outputs are described in the following sections.
Method
The method for an Authorization flow-node is:
• Get Credential - Retrieves a credential based on a given name.
Parameters
The Authorization flow-node parameter is described in the following section.
Get Credential parameters
The Get Credential method parameter is:
Parameter Type Description Configuration selection
name string The name of the Selector, String

configured credential to
find and return
Outputs
The Authorization flow-node outputs are described in the following section.
Get Credential outputs
The Get Credential method outputs are:

Output Type Description Save output value as:
Next any - $.credential
Error string Error retrieving the $.error

credential with the
specified name.
Base64 flow-node
The flow-node methods, parameters, and output for the Base64 flow-node are described in the following
sections. The Base64 flow-node is created when NPM installs the @axway/api-builder-plugin-fn-
base64 plugin. The Base64 flow-node plugin is included in the default application, but it can be removed.
Methods
The Base64 flow-node default methods are:
• Decode - Decodes base-64 encoded data.

• Encode - Encodes base-64 data.
Parameters
The Base64 flow-node parameters are described in the following sections.
Decode parameters
The Decode method parameters are:
Parameter Type Default Description Configuration

selection
data string - The date to Selector, String

decode.
as string "buffer" Expected decoded Selector, String

data format.
The as parameter can be enabled or disabled.
Encode parameters
The Encode method parameter is:
data any The data to encode. Selector, String, Number,

Boolean, Object, Array,
Null

Outputs
The Base64 flow-node outputs are described in the following sections.
Decode outputs
The Decode method outputs are:
Decoded string The base-64 decoded $.decoded

data.
Error any - $.b64error
Encode outputs
The Encode method output is:
Encoded string The base-64 encoded $.b64data

data.
Codeblock flow-node
Beginning with the Cairo release, Codeblocks are deprecated [D028] and will be removed in a future version
of the product.
This document describes a Codeblock flow-node and provides information on Codeblock flow-node.
Name Description
Codeblock A flow-node that can be used for executing user

code and returns the response. This node allows
custom business logic to be executed as part of the
flow.
The Codeblock flow-node configuration, metadata, functionality, methods, parameters, and outputs for the
Greet Codeblock flow-node are described in the following sections. Each method in a Codeblock flow-node
corresponds to a single codeblock. The Greet Codeblock flow-node is created when a new application is
created, but it can be deleted.
Instance configuration (config)
Property Description Required Type
method The name of the yes string

Codeblock to execute.

The typical usage of code block flow-nodes involves setting parameters, mapping responses, and setting
required configs as noted in the example below.
Configuration example
"block.0": {
"type": "Codeblock",
"config": {
"method": "Greet"
},
"parameters": [
{
"name": "username",
"value": "$.params.username"
}
],
"response": {
"context": {
"$": "greeting"
},
"routes": null
}
}
Metadata
Codeblock metadata should be included in the /codeblocks directory of an API Builder Project. It is
defined as a JSON file with the following properties:
Property Description Required Type
name The name of the yes string

Codeblock.
description The description of the yes string

Codeblock.
path The relative path to the yes string

function to be invoked.
parameter Schema containing yes object

describing all the input
parameters
outputs Map of outputs that the yes object

codeblock can invoke
Metadata example
Greet.json
{
"name": "Greet",
"description": "Some codeblock to run with Greet flow",
"path": "Greet.js",

"parameter": {
"additionalProperties": false,
"properties": {
"username": {
"type": "string"
}
}
},
"outputs": {
"next": {},
"error": {}
}
}
The functional part of a Codeblock should be a .js file which exports a function of the following signature:
invoke(apibuilder, params, cb);
• apibuilder <APIBuilder> - The API Builder instance.

• params <Object> - Key/value pairs of parameters passed to the node instance.
• cb <Function> - Callback.
• err - Error. Passing this will cause the flow to cease processing and a 500 error to be returned
from the endpoint which called it.
• response - The data to be returned as the node response.
Warning: Most of the time errors should be returned in the callback as a standard response. Using the first
parameter to return errors is the same as throwing an error in the Codeblock and should rarely
need to be used.
Functionality example
Greet.js
function invoke(apibuilder, params, cb) {
const salutation = apibuilder.config.helloworld.salutation;
if (!params.username) {
return cb.error(null, {
message: 'Invalid name'
});
}
const body = salutation + ' ' + params.username;
cb(null, body);
}
exports = module.exports = invoke
Method
The default method for the Greet Codeblock flow-node is:
• Greet - The codeblock to run with the greet flow.

Parameter
The Greet method parameter is:
Parameter Type Configuration selection
username string Selector, String
Outputs
The Greet method outputs are:
next string The codeblock $.greeting

completed.
error object The codeblock failed to $.error

complete.
Compose flow-node
The Compose (DoT) flow-node methods, parameters, and outputs are described in the following sections.
The Compose flow-node is created when NPM installs the @axway/api-builder-plugin-fn-dot
plugin. The Compose flow-node plugin is included in the default application, but it can be removed. For
additional DoT flow-node information, refer to DoT flow-node.
Installing the Compose (DoT) flow-node module may report a security vulnerability with doT. This is
because doT templates can be used to execute malicious JavaScript.
Templates should never come from untrusted sources. If you trust all the templates that you use, then you
can safely ignore the vulnerability and continue to use this plugin.
This plugin is no longer bundled with new API Builder projects. We suggest using @axway/api-builder-
plugin-fn-javascript instead of the formatObject method, or @axway/api-builder-plugin-
fn-mustache instead of formatString.
Methods
The default methods for a Compose flow-node are:
• Format object - Compose an object by evaluating a template. The evaluated template is JSON
parsed and so must be a valid JSON encoded string. For additional information, see https://
olado.github.io/doT.
• Format string - Compose a string by evaluating a template. For additional information, see https://
olado.github.io/doT.
Parameters
The Compose flow-node parameters are described in the following sections.

Format object parameters
The Format object method parameters are:
data object The data to evaluate the Selector, Object

template with. Use $ to
access the entire
context.
template string The doT template. Selector, String
Format string parameters
The Format string method parameters are:
data object The data to evaluate the Selector, Object

template with. Use $ to
access the entire
context.
template string The doT template. Selector, String
Outputs
The Compose flow-node outputs are described in the following sections.
Format object outputs
The Format object method outputs are:
Next any - $.value
Error any This output is triggered $.error

if the evaluated
template is not a valid
JSON string. The output
value is the error object.
Format string outputs
The Format string method outputs are:
Next any - $.value


if the evaluated
template is not valid.
The output value is the
error object.
Condition flow-node
The Condition flow-node methods, parameters, and outputs are described in the following sections.
Methods
The default methods for a Condition flow-node are:
• equals - Tests if a value is equal.

• exists - Tests if a value exists, true or false.
• greater-than - Tests if a value is greater than another value.
• greater-than-equal - Tests if a value is greater than or equal to another value.
• less-than - Tests if a value is less than another value.
• less-than-equal - Tests if a value is less than or equal to another value.
Parameters
The Condition parameters are described in the following sections.
equals parameters
The equals method parameters are:
source any The input to test. Selector, String, Number,

Null
value any The value to test input Selector, String, Number,

against. Boolean, Object, Array,
Null
exists parameters
The exists method parameter is:

Null

greater-than parameters
The greater-than method parameters are:

Null

Null
greater-than-equal parameters
The greater-than-equal method parameters are:

Null

Null
less-than parameters
The less-than method parameters are:

Null

Null
less-than-equal parameters
The less-than-equal method parameters are:

Null


Null
Outputs
The Condition flow-node outputs are described in the following sections.
equals outputs
The equals method outputs are:
true boolean The condition tested $.equals

true.
false boolean The condition tested $.equals

false.
exists outputs
The exists method outputs are:
true boolean The condition tested $.exists

true.
false boolean The condition tested $.exists

false.
greater-than outputs
The greater-than method outputs are:
true boolean The condition tested $.greaterThan

true.
false boolean The condition tested $.greaterThan

false.
greater-than-equal outputs
The greater-than-equal method outputs are:

true boolean The condition tested $.greaterThanEqual

true.
false boolean The condition tested $.greaterThanEqual

false.
less-than outputs
The greater-than-equal method outputs are:
true boolean The condition tested $.lessThan

true.
false boolean The condition tested $.lessThan

false.
less-than-equal outputs
The less-than-equal method outputs are:
true boolean The condition tested $.lessThanEqual

true.
false boolean The condition tested $.lessThanEqual

false.
Delay flow-node
The Delay flow-node method, parameter, and output are described in the following sections.
Method
The method for a Delay flow-node is:
• delay - Wait for a configured amount of time before continuing to the next flow-node.
Parameter
The Delay flow-node parameter is described in the following section.
delay parameter
The delay method parameter is:


selection
delay integer - The length of Selector, Number

delay, in
milliseconds.
Output
The Delay flow-node output is described in the following section.
delay output
The delay method output is:
next integer The delay is completed. $.delayed
DoT flow-node
Installing this module may report a security vulnerability with doT. This is because doT templates can be
used to execute malicious JavaScript.
Templates should never come from untrusted sources. If you trust all the templates that you use, then you
can safely ignore the vulnerability and continue to use this plugin.
This plugin is no longer bundled with new API Builder projects. We suggest using @axway/api-builder-
plugin-fn-javascript instead of the formatObject method, or @axway/api-builder-plugin-
fn-mustache instead of formatString.
Compose flow-node templates

API Builder's Compose flow-node allows you to transform the structure of your data within an orchestrated
flow. It uses doT, a powerful template engine similar to Mustache or Handlebars. The Compose flow-node
( @axway/api-builder-plugin-fn-dot ) comes installed with all new API Builder projects.
Additional information about the usage of the doT plugin can be found in the plugin's README, and
information about the doT template language can be found here.
The Compose flow-node has two methods: Format string and Format object. The Format
string method will run the template engine and return the result as a string. The Format object will run
the template engine and parse the result as a JSON object. Both functions require two
parameters: data and template.
Parameter: data
The data parameter refers to content which is provided to the template when it is evaluated at runtime. It is
the selector or JSON object that you want to pass to the doT template engine for formatting. The data can
be a selector or a JSON object. A JSON object can be a JSON string, null, Boolean, array, or IIRC. In API
Builder flows, the $ is a JSON path selector that selects data from the runtime context. You can pass the
whole runtime context into the doT template engine or you can use the selector to choose and pass specific

data elements. For example, you can use $.params.username to return a string or $.username to return
an array of usernames. At design time, it is useful to have an understanding of the data that you are
querying and an understanding of what the JSON path selector will return.
Parameter: template
A doT template is a string which contains a mixture of static and dynamic content. Together with
the template, the data parameter is fed into the template engine at runtime. The data parameter is referred
to as "it" within the template.
Dynamic content is evaluated inside double curly brackets {{}}. In this example, "My name
is {{=it}}", the string "My name is" is static content and "{{=it}}" is calculated dynamically
based on the data parameter passed into the template at runtime.
The curly brackets {{}} can be used in many ways, based on how you want to dynamically generate the
resulting object or string. The most common one is {{= }}. This is the "interpolation delimiter", in other
words, the code inserted within the curly brackets will be stringified and included in the output data. This is
a list of all the delimiters:
Delimiter Description
{{ }} Evaluation
{{= }} Interpolation
{{! }} Interpolation with encoding
{{# }} Compile-time evaluation/includes and partials
{{## #}} Compile-time defines
{{? }} Conditionals
{{~ }} Array iteration
Simple examples of data, templates, JSON path, and interpolation
Data Template Output
{{="Hello"}}, Joe Hello, Joe
"Greetings" {{=it}}, Joe Greetings, Joe
{ "greeting": "Good {{=it.greeting}}, Joe Good day, Joe

day" }
[ 1, 2, 3, 4 ] {{=it.includes(5)}} false

Format string example
Here you can see how data and templates are used
together in the flow editor for outputting a string. The
"Format string" method has been selected. As with
any values, data can be input into the doT flow-node
as hard-coded object value, or as a selector. In this
case, the selector $.params is used. The $.params
selector refers to an object containing parameters
that were included in the request. In this example,
imagine that $.params looks like the following
object when the flow is invoked:
$.params Template Output
{ "username My name is My name is

": "Joe" } {{=it.usern Joe
ame}}
With the template value of "My name is

{{=it.username}}.", the flow-node will take the

username property from the object passed in as data

and evaluate the string as "My name is Joe Bloggs."
Format object example
This example shows how to build a JSON object

dynamically using the Format object method of
the doT flow-node. Similar to the previous example,
the interpolation delimiter {{= }} is used to insert
dynamic data. In this template, a JSON object is
formatted where the keys are static and the values
are dynamically provided.
{ { {
"username": "name": "name":
"Joe", "{{=it.user "Joe",
"favoriteFo name}}", "likes":
ods": "likes": "apple
[ "apple", "{{=it.favo

"orange" ] riteFoods}} orange"

} " }
}
doT Examples
The following sections provide doT flow-node examples.
Interpolation
"foobar" "{{= it.match(/ "FOO"

foo/).toString().toUpper
Case() }}"
Evaluation with HTML encoding
"You & I" {{!it}} like API You & I like API Builder!
Builder!
Compose a new JSON object
{ { {
"username": "Joe", "name": "name": "Joe",
"favoriteFoods": "{{=it.username}}", "likes": [ "apples",
[ "apples", "oranges" ] "likes": "oranges" ]
} {{=JSON.stringify(it.fav }
oriteFoods)}}
}
Compile-time definitions
{ {{##def.snippet1: Hello, Joe - you are

"name":"Joe", {{=it.name}} {{? authorized
"auth": true it.auth}} - you are
} authorized{{?}}
#}} Hello,
{{#def.snippet1}}

Compile-time definitions with parameters
{ {{##def.block1:param: <user authorized>Joe</

"name":"Joe", <user {{? user>
"auth": true param.auth}}authorized{{
} ?}}>{{=param.name}}</
user>
#}}
{{#def.block1 :it }}
Array manipulation
{ { {
"favoriteFoods": "{{=it.username}}", "likes": "apples and
[ "apples", "oranges" ] "likes": oranges"
} "{{=it.favoriteFoods.joi }
n(' and ')}}"
}
Conditionals
{ My name is My name is Joe.

"username": "Joe" {{=it.username}}{{?
} it.favoriteFoods }} and
I like
{{=it.favoriteFoods.joi
n(' and ')}}{{?}}.
{ My name is My name is Joe and I

"username": "Joe", {{=it.username}} {{? like apples and oranges.
"favoriteFoods": it.favoriteFoods }} and
[ "apple", "orange" ] I like
} {{=it.favoriteFoods.joi
n(' and ')}}{{?}}.
Conditional if/else
{ {{? it.username === I don't know you

"username": "Sam" "Joe" }}
} Hello Joe!
{{??}}

I don't know you

{{?}}
Array loops
["apple", "banana", [ [ "apple-0" ,

"orange"] {{~ it :value:i}} "banana-1" ,
"{{=value}}-{{=i}}" "orange-2" ]
{{? i < it.length - 1}},
{{?}}
{{~}}
]
JavaScript function with no parameter
{} {{##def.myfunc = {timestamp:
function() { 1535531752947}
return Date.now();
}
#}} {timestamp:
{{#def.myfunc()}}}
JavaScript function with a string parameter
{ name: "Joe" } {{##def.myfunc = {user: "Joe"}

function(str) {
return str;
}
#}} {user:
"{{#def.myfunc( "\{\
{=it.name\}\}" )}}"}
JSON stringify
{ { {
"favoriteFoods": {{=JSON.stringify(it.use "likes": "apple orange"
[ "apple", "orange" ] rname)}}, }
} "likes":
{{=JSON.stringify(it.fav
oriteFoods)}}
}

HTTP flow-node
The HTTP flow-node method, parameter, and output are described in the following sections.
Method
The method for an HTTP flow-node is:
• setHTTPResponse
Parameter
The HTTP flow-node parameter is described in the following section.
setHTTPResponse parameter
The setHTTPResponse method parameters are:
Parameter Type Minimum Maximum Description Configuration

selection
status integer 100 599 - Selector,

Number
body any - - - Selector, String,

Number,
Boolean,
Object, Array,
Null
headers object - - - Selector, Object
The body and headers parameters can be enabled or disabled.
Output
The HTTP flow-node output is described in the following section.
setHTTPResponse output
The setHTTPResponse method does not have any configurable outputs.
JSON flow-node
The JSON flow-node methods, parameters, and output are described in the following sections. The JSON
flow-node is created when NPM installs the @axway/api-builder-plugin-fn-json plugin. The JSON
flow-node plugin is included in the default application, but it can be removed.
Methods
The default methods for a JSON flow-node are:

• Parse - The parse method parses a JSON string, constructing the JavaScript value or object
described by the string.
• Stringify - The stringify method converts a JavaScript value to a JSON string.
Parameters
The JSON flow-node parameters are described in the following sections.
Parse parameters
The Parse method parameter is:
json string The JSON string to Selector, String

parse.
Stringify parameters
The Stringify method parameters are:
value any The value to convert to a Selector, String, Number,

JSON string. Boolean, Object, Array,
Null
space any A string or number Selector, String, Number,

object that's used to Boolean, Object, Array,
insert white space into Null
the output JSON string
for readability purposes.
If this is a number, it
indicates the number of
space characters to use
as white space; this
number is capped at 10.
If this is a string, its
maximum length is 10;
the string is used as
white space. If this
parameter is not
provided, no white
space is used.
The space parameter can be enabled or disabled.
Outputs
The JSON flow-node outputs are described in the following sections.

Parse outputs
The Parse method outputs are:
Next any - $.value

if the input is not a valid
JSON string. The output
value is the error object.
Stringify output
The Stringify method output is:
Next string - $.json
JavaScript flow-node
Overview
The Javascript plugin, @axway/api-builder-plugin-fn-javascript, allows the user to execute
JavaScript code inside a Flow.
To install the Javascript plugin, execute the following command:
npm install --no-optional @axway/api-builder-plugin-fn-javascript
For additional getting started information, refer to the API Builder Getting Started Guide.
Methods
The following sections provide details of the JavaScript flow-note Execute method.
Execute
Allows the execution of JavaScript code and returns the result of the execution as the Flow Node's output.
Parameters
Parameter Type Description Configuration Required

selection
code string A JavaScript Selector, String Yes

function body.
Supports àwait`

and returning
promises.
data any The value to apply Any No

as the `data`
argument to the
JavaScript
code. For objects
and arrays, `data`
is passed by
reference.
Unsafe mode boolean USE WITH Selector, Boolean No

CAUTION. When
enabled,
JavaScript is not
executed in a
sandboxed
environment and
all globals are
available.
Parameter: code
The code parameter is where you define the JavaScript you would like to execute. The code should be
provided as a String. The data parameter is fed into the code snippet as an argument.
It is important to note that the specified JavaScript code is executed in a sandboxed environment. Meaning
that the specified code snippet is isolated from the rest of the server when executed.
Parameter: data
The data parameter refers to content which is passed to the JavaScript code. The content is passed as an
argument in the code as "data". The parameter can be any data type. For example, you could use $ Selector
to access the entire context, or limit it to a specific subset (e.g. to access parameters as parameters -
$.params).
It is not recommended to provide the code as a Selector. It is a security risk to execute code obtained from
unknown sources.
Advanced Parameter: Unsafe mode
By default, the code is executed in a sandboxed environment with its own context so it is very difficult to
modify the state of the API Builder service. Most JavaScript can still be used here (including promises and
await) with the exception of many global functions such as setTimeout, the Function constructor and
require. Enabling Unsafe mode allows accessing the previously unavailable globals. However, be aware that
it also provides access to the same context as the rest of the API Builder service, meaning that potentially
bad things can be achieved. Only enable Unsafe mode if you know what you're doing.

Outputs
Next any The data returned by the $.result

code snippet. If
returning a promise, this
will be the data that the
promise resolves with.

if the code snippet
throws an error or
returns a promise which
rejects. The output value
an object with the error
message, or the rejected
value.
How to use the JavaScript plugin

After the installation of the JavaScript plugin and editing a Flow, you will find the JavaScript flow-node in the
Core section:
You can drag and drop the JavaScript flow-node into the Flow Graph to expand its details:

Example 1 - Greet Flow
Here is how you could use the JavaScript flow-node to achieve the same functionality as our Greet Flow
example:
First, you would need to determine the data you would like to pass to your function. For the Greet Flow you
will need both the $.config, as the salutation is stored there, and the user's name, which comes
from $.params.
So let's pass the entire context with the $ selector and use JavaScript code to format the message as we
have seen in the Greet Flow.

We could use a simple template literal to construct the message:
Let's hook everything up as we have seen before to the success node and bad request node.
Make sure the outputs of the JavaScript flow-node are correctly used within the HTTP flow-nodes. As
described above, the default outputs are $.result and $.error:

You could invoke your newly created flow through the debugger:
Which would return the already familiar salutation:
Example 2 - Format Object
Input Code Output
data = { // Maps a hero name to {

"firstName": "Bruce", the Universe the "heroName": "Batman",
"lastName": "Wayne", character belongs to "secretName": "Bruce
"heroName": "Batman" const Wayne",
}; heroNamesToUniverseMappe

r = { "universe": "DC"
'Batman': 'DC', }
'Flash': 'DC',
'Spiderman': 'Marvel',
'Iron Man': 'Marvel'
};
return {
heroName:
data.heroName,
secretName:
data.firstName + ' ' +
data.lastName,
universe:
heroNamesToUniverseMappe
r[data.heroName] ||
'N/A'
};
Example 3 - String Concatenation
Input Code Output
data = { return data.firstName + "Bruce Wayne"

"firstName": "Bruce", ' ' + data.lastName;
"lastName": "Wayne"
};
data = { return `$ "Bruce Wayne"

"firstName": "Bruce", {data.firstName} $
"lastName": "Wayne" {data.lastName}`;
};
Example 4 - Processing Data
Input Code Output
data = let result = 0; 6

["1","2","3","4","5"];
data.forEach(function(el
ement) {
const number =
parseInt(element);
if(number % 2 == 0){
result +=
number;
}
});
return result;

data = return data.map(item => 6

["1","2","3","4","5"]; parseInt(item))
.filter(number =>
number % 2 == 0)
.reduce((sum, number)
=> sum + number);
Example 5 - Object Manipulation - Combining two objects
Input Code Output
data = { const companyDetails = { {

"birthYear": 1989, company: 'Axway', "birthYear": 1989,
"name": "Peter Parker" companyAddress: "name": "Peter
}; 'Phoenix, US' Parker",
}; "company": "Axway",
"companyAddress":
return "Phoenix, US"
Object.assign(data, }
companyDetails);
Example 6 - Object Manipulation - Merging with spread
Input Code Output
data = { return { { "birthYear": 1989,

"birthYear": 1989, ...data, "name": "Peter
"name": "Peter Parker" Parker",
}; company: 'Axway', "company": "Axway",
companyAddress: "companyAddress":
'Phoenix, US' "Phoenix, US"
}; }
Model flow-nodes
Model flow-nodes can be configured by selecting a method and defining the parameters and outputs in the
API Orchestration flow editor. The default Model flow-node methods are count, create, delete,
deleteAll, distinct, findAll, findAndModify, findByID, query, update, and upsert. There is
one Model flow-node for model listed in API Orchestration user interface. The methods, parameters, and
outputs for each Model flow-node are described in the following topics:
• count method
• create method
• deleteAll method
• delete method
• distinct method
• findAll method

• findAndModify method
• findByID method
• query method
• update method
• upsert method
count method
count method
This document describes the count method, parameter, and output information.
Method
• count - Gets a count of records.
Parameter
The count method parameter is:

selection
where string - The JSON- Selector, String

encoded object
specifying field
constraints. The
field name is the
key and the value
is the constraint
statement or value.
The where parameter can be enabled or disabled.
Where parameter
The count method where parameter operators are:
Name Description Syntax
$eq Count records that are equal to a {< field >: { $eq :<
specified value. The $eq operator value > } }
matches records where the value
of a field equals the specified
value. The $eq expression is
equivalent to { field:
<value> }.
$ne Count records that are not equal {field: {$ne: value} }
to a specified value. The $ne
operator selects the records

where the value of the field is

not equal to the specified value.
This includes records that do not
contain the field.
$gt Count records that are greater {field: {$gt: value} }

than a specified value. The $gt
operator selects those records
greater than the specified value.
$lt Count records that are less than {field: {$lt: value} }
a specified value. The $lt
less than the specified value.
$gte Count records that are greater {field: {$gte: value} }

than or equal to a specified value.
The $gte operator selects the
records where the value of the
field is greater than or equal to
a specified value.
$lte Count records that are less than { field: { $lte:

or equal to a specified value. The value} }
$lte operator selects the
field is less than or equal to
the specified value.
$in Count records that match any of { field : { $in : [ <

the values specified in an array. value1 > ,< value2
The $in operator selects the > , ...< valueN > ] } }
records where the value of a
field equals any value in the
specified array.
$nin Count records that do not match { field: { $nin:

any of the values specified in an [ <value1>, <value2> ...
array. The $nin operator selects <valueN> ]} }
the records where the field
value is not in the specified array
or the field does not exist.
Output
The count method output is:

next number Successfully counted $.count

records.
create method
create method
This document describes the create method, parameter, and output information.
Method
• create - Creates a new model object.
Parameter
The create method parameter is:
data object Selector, Object
Output
The create method output is:
next object Successfully created a $.created

record.
delete method
delete method
The document describes the delete method, parameter, and outputs.
Method
• delete - Deletes the model object.
Parameter
The delete method parameter is:
id any Selector, String

Outputs
The delete method outputs are:
next object Successfully deleted a $.delete

record.
notfound any No model instance -

found.
deleteAll method
deleteAll method
The document describes the deleteAll method, parameters, and output.
Method
• deleteAll - Deletes all the model objects.
Parameters
There are no configurable deleteAll method parameters.
Output
The deleteAll method output is:
next array Successfully deleted all $.deletedAll

records.
distinct method
distinct method
The document describes the distinct method, parameters, and output.
Method
• distinct - Finds unique values using the provided field.
Parameters
The distinct method parameters are:


selection
field string - The field must be Selector, String

distinct.
limit integer 10 The number of Selector, Number

records to fetch.
order object - A dictionary of key- Selector, Object

value pairs
describing the
field(s) for sorting.
The field name is
the key and the
value is set to
either -1 for
ascending order or
1 for descending
order.
skip integer - The number of Selector, Number

records to skip.

encoded object
specifying field
constraints. The
field name is the
key and the value
is the constraint
statement or value.
The limit, order, sel, skip, unsel, and where parameters can be enabled or disabled.
Where parameter
The distinct method where parameter operators are:
$eq Find distinct records that are { < field >: { $eq : <
equal to a specified value. The value > } }
$eq operator matches records
where the value of a field
equals the specified value. The
$eq expression is equivalent to
{ field: <value> }.
$ne Find distinct records that are not {field: {$ne: value} }
equal to a specified value. The
$ne operator selects the records


contain the field.
$gt Find distinct records that are {field: {$gt: value} }

greater than a specified value.
The $gt operator selects those
field is greater than the
specified value.
$lt Find distinct records that are less {field: {$lt: value} }
than a specified value. The $lt
$gte Find distinct records that are {field: {$gte: value} }

greater than or equal to a
specified value. The $gte
specified value.
$lte Find distinct records that are less { field: { $lte:

than or equal to a specified value. value} }
The $lte operator selects the
$in Find distinct records that match { field : { $in : [ <

any of the values specified in an value1 > , < value2
array. The $in operator selects > , ... < valueN > ] } }
the records where the value of a
specified array.
$nin Find distinct records that do not { field: { $nin:

match any of the values specified [ <value1>, <value2> ...
in an array. The $nin operator <valueN> ]} }
selects the records where the
field value is not in the
specified array or the field
does not exist.

Output
The distinct method output is:
next array Successfully found all $.distinct

unique values of the
field.
findAll method
findAll method
The document describes the findAll method, parameters, and output.
Method
• findAll - Finds all model instances.
Parameters
There are no configurable findAll method parameters.
Output
The findAll method output is:
Outputs Type Description Save output value as:
next array Successfully found all $.foundAll

records.
findAndModify method
findAndModify method
The document describes the findAndModify method, parameters, and outputs.
Method
• findAndModify - Finds one model instance and modifies it.
Parameters
The findAndModify method parameters are:


selection
data object - - Selector, Object
args object - Optional Selector, Object

parameters.

records to fetch.

value pairs
describing the
The field name is
the key and the
value is set to
either -1 for
ascending order or
1 for descending
order.
sel object - A dictionary of key- Selector, Object

value pairs
describing which
fields to include in
the query results.
The field name is
the key and the
value is set to 1.

records to skip.
unsel object - A dictionary of key- Selector, Object

value pairs
describing which
fields to exclude
from the query
results. The field
name is the key
and the value is set
to 1.

encoded object
specifying field
constraints. The
field name is the
key and the value


selection
is the constraint
statement or value.
The args, limit, order, sel, skip, unsel, and where parameters can be enabled or disabled.
Where parameter
The findAndModify method where parameter operators are:
$eq Find and modify records that are { < field >: { $eq : <
equal to a specified value. The value > } }
$eq operator matches records
where the value of a field
equals the specified value. The
$eq expression is equivalent to
{ field: <value> }.
$ne Find and modify records that are {field: {$ne: value} }
not equal to a specified value.
The $ne operator selects the
field is not equal to the
specified value. This includes
records that do not contain the
field .
$gt Find and modify records that are {field: {$gt: value} }
greater than a specified value.
The $gt operator selects those
field is greater than the
specified value.
$lt Find and modify records that are {field: {$lt: value} }
less than a specified value. The
$lt operator selects the records
$gte Find and modify records that are {field: {$gte: value} }
specified value. The $gte
specified value.

$lte Find and modify records that are { field: { $lte:

less than or equal to a specified value} }
value. The $lte operator selects
the records where the value of
the field is less than or equal
to the specified value.
$in Find and modify records that { field : { $in : [ <

match any of the values specified value1 > , < value2
in an array. The $in operator > , ... < valueN > ] } }
value of a field equals any
value in the specified array.
$nin Find and modify records that do { field: { $nin:

not match any of the values [ <value1>, <value2> ...
specified in an array. The $nin <valueN> ]} }
where the field value is not in
the specified array or the field
does not exist.
Outputs
The findAndModity method outputs are:
next object Successfully found and $.foundAndModified

modified a record.
notfound any No matching model -

found.
findByID method
findByID method
The document describes the findByID method, parameter, and outputs.
Method
• findByID - Finds model instance by ID.
Parameter
The findByID method parameter is:

Parameter Type Default Description JSONPath Configuration

selections
id any - - $.params.id Selector, String
Outputs
The findByID method outputs are:
next object Successfully found a $.foundByID

model instance by ID.

found.
query method
query method
The document describes the query method, parameters, and output.
Method
• query - Queries for particular model records.
Parameters
The query method parameters are:

selection

records to fetch.

value pairs
describing the
The field name is
the key and the
value is set to
either -1 for
ascending order or
1 for descending
order.
sel object - A dictionary of key- Selector, Object

value pairs
describing which


selection
fields to include in
the query results.
The field name is
the key and the
value is set to 1.

records to skip.
unsel object - A dictionary of key- Selector, Object

value pairs
describing which
fields to exclude
from the query
results. The field
name is the key
and the value is set
to 1.

encoded object
specifying field
constraints. The
field name is the
key and the value
is the constraint
statement or value.
All parameters can be enabled or disabled.
Where parameter
The query method where parameter operators are:
$eq Query records that are equal to a { < field >: { $eq : <
specified value. The $eq value > } }
operator matches records where
the value of a field equals the
specified value. The $eq
expression is equivalent to
{ field: <value> }.
$ne Query records that are not equal {field: {$ne: value} }
to a specified value. The $ne


contain the field.
$gt Query records that are greater {field: {$gt: value} }

than a specified value. The $gt
operator selects those records
greater than the specified value.
$lt Query records that are less than a {field: {$lt: value} }
specified value. The $lt operator
value of the field is less than
$gte Query records that are greater {field: {$gte: value} }

than or equal to a specified value.
The $gte operator selects the
field is greater than or equal to
a specified value.
$lte Query records that are less than { field: { $lte:

or equal to a specified value. The value} }
$lte operator selects the
$in Query records that match any of { field : { $in : [ <

the values specified in an array. value1 > , < value2
The $in operator selects the > , ... < valueN > ] } }
records where the value of a
specified array.
$nin Query records that do not match { field: { $nin:

any of the values specified in an [ <value1>, <value2> ...
array. The $nin operator selects <valueN> ]} }
the records where the field
value is not in the specified array
or the field does not exist.
Outputs
The query method output is:

next array Successfully queried the $.queried

record.
update method
update method
The document describes the update method, parameters, and outputs.
Method
• update - Updates a model instance.
Parameters
The update method parameters are:
data object Dependent on Selector, Object

configured model fields.
id string - Selector, String
Outputs
The update method outputs are:
next object Successfully updated $.updated

the model instance.

found.
upsert method
upsert method
The document describes the upsert method, parameters, and outputs.
Method
• upsert - Creates a model record if not found, or updates the model record if found.
Parameter
The upsert method parameter is:

Parameter Type Configuration selections
data object Selector, Object
Outputs
The upsert method outputs are:
update object Successfully updated $.model

the model.
insert object Successfully inserted $.model

the model.
Mustache flow-node
The following sections describe Mustache flow-node methods, parameters, and outputs.
The Mustache flow-node plugin is currently not included in the default application, but it can be installed
manually with:
npm install --no-optional @axway/api-builder-plugin-fn-mustache
Method
The Mustache flow-node has a single method called Format string. It composes a string by evaluating
a template using Mustache. For additional information, refer to the Mustache template language.
Parameters
The Format string method parameters are:
data any The value to assign to Any

the "data" variable in the
template.
template string The Mustache template. Selector, String

For example: Hi
{{data.user}}
The data parameter refers to content which is provided to the template when it is evaluated at runtime. It is
the selector or value that you want to pass to the Mustache template engine to provide dynamic values to
the resulting string.

Providing dynamic data using a JSONPath Selector
In API Builder flows, the $ is a JSON path selector that selects data from the whole runtime context. You
can also modify the selector to choose and pass specific data elements. For example, you can
use $.params.username to refer to the username parameter in the flow. At design time, it is useful to
have an understanding of the data that you are querying and an understanding of what the JSON path
selector will return.
The template parameter refers to the Mustache template, which is a string that contains a mixture of
static and dynamic content. Both the template and data parameters are fed into the template engine
at runtime. The data parameter is referred to as "data" within the template. Dynamic content is evaluated
inside double curly brackets {{}}. In this example, "My name is {{data.username}}", the string "My
name is" is static content and "{{data.username}}" is calculated dynamically based on the data
parameter passed into the template at runtime.
Outputs
The Format string method outputs are:
Next string The formatted string. $.value
Error object The error object thrown $.error

when evaluating an
invalid template.
Examples
In this section, some examples are shown. The examples show what the Output would be for specific values
for data and template parameters.
Example 1: Property "data" set to "$"
data template Output
{ params: { "username": My name is My name is Joe

"Joe" } } {{data.params.username}}
Example 2: Property "data" set to "$.param"
{ "username": "Joe" } My name is My name is Joe

{{data.username}}

Example 3: Property "data" set to a custom object
{ "firstname": "John", My name is My name is John Doe

"lastname": "Doe" } {{data.firstname}}
{{data.lastname}}
Example 4: Greet example
This is the Greet example that comes with the newly scaffolded service.
The data property is set to "$" which has access to the config and params properties.
{ {{data.config.helloworld Howdy, John!

"config": { .salutation}},
"helloworld": { {{data.params.username}}
"salutation": "Howdy" !
}},
"params":{ "username":
"John" }
}
Example 5: Data with array property
{"usernames": ["John", Hello Hello John, Jay!

"Jay"]} {{data.usernames}}!
Example 6: Sections
{ "firstname": "John", {#data}Hi {{firstname}} Hi John Doe

"lastname": "Doe" } {{lastname}}{/data}
Example 7: Array of objects
By wrapping a template in a section ({{#variable}}inner{{/variable}}), where variable is an

array, the inner template content will be repeated once for each item in the array.
[{ "item": "Oranges", My Items: My Items:

"price": 10 }, { "item": {{#data}} Oranges: £10
"Apples": "price": 5 }]} {{item}}: £{{price}} Apples: £5
{{/data}}

REST flow-node
The REST flow-node methods, parameters, and output are described in the following sections. The REST
flow-node is created when NPM installs the @axway/api-builder-plugin-fn-restclient plugin.
The REST flow-node plugin is included in the default application, but it can be removed.
Methods
The default methods for a REST flow-node are:
• DELETE - Use DELETE APIs to delete resources.

• GET - Use GET APIs to retrieve resources only and not to modify them in any way.
• HEAD - Use HEAD APIs to request the headers that are returned if the specified resource would be
requested with a GET API.
• OPTIONS - Use OPTIONS APIs to determine the options and requirements associated with a resource.
• PATCH - Use PATCH APIs to make partial updates on a resource.
• POST - Use POST APIs to create new resources.
• PUT - Use PUT APIs primarily to update existing resources, if a resource does not exist then the API
may decide whether or not to create a new resource.
Parameters
The REST flow-node parameters are described in the following sections.
DELETE parameters
The DELETE method parameters are:

selection
URL string - The target URL. Selector, String
Headers object - The HTTP headers Selector, Object

to set.
Advanced HTTP
Options
Follow redirect boolean true Follow HTTP 3xx Selector, Boolean

responses as
redirects.
Insecure boolean false Do not require the Selector, Boolean

SSL certificates to
be valid.
Maximum integer 10 The maximum Selector, Number

redirects number of

redirects before
aborting.
The Headers, Follow redirect, Insecure, and Maximum redirects parameters can be enabled or
disabled.
GET parameters
The GET method parameters are:

selection

to set.
Advanced HTTP
Options

responses as
redirects.

SSL certificates to
be valid.

redirects number of
redirects before
aborting.
Response string - The response body Selector, String

encoding encoding if you
expect binary use
binary as the
encoding.
The Headers, Follow redirect, Insecure, Maximum redirects, and Response encoding
parameters can be enabled or disabled.
HEAD parameters
The HEAD method parameters are:

selection


to set.
Advanced HTTP
Options

responses as
redirects.

SSL certificates to
be valid.

redirects number of
redirects before
aborting.
disabled.
OPTIONS parameters
The OPTIONS method parameters are:

selection

to set.
Advanced HTTP
Options

responses as
redirects.

SSL certificates to
be valid.

redirects number of
redirects before
aborting.
disabled.

PATCH parameters
The PATCH method parameters are:

selection
Body any - The content to Selector, String,

send. Number, Boolean,
Object, Array, Null

to set.
Advanced HTTP
Options

responses as
redirects.

SSL certificates to
be valid.

redirects number of
redirects before
aborting.

encoding encoding. If you
expect binary to
use binary as the
encoding.
The Follow redirect, Headers, Insecure, Maximum redirects, and Response encoding
POST parameters
The POST method parameters are:

selection

Object, Array, Null


to set.
Advanced HTTP
Options

responses as
redirects.

SSL certificates to
be valid.

redirects number of
redirects before
aborting.

expect binary use
binary as the
encoding.
PUT parameters
The PUT method parameters are:

selection

Object, Array, Null

to set.
Advanced HTTP
Options

responses as
redirects.


SSL certificates to
be valid.

redirects number of
redirects before
aborting.

expect binary use
binary as the
encoding.
Outputs
The REST flow-node outputs are described in the following sections.
DELETE outputs
The DELETE method outputs are:
2XX object - $.response
Error any - $.error
GET outputs
The GET method outputs are:

Error any - $.error
HEAD outputs
The HEAD method outputs are:
Error any - $.error
OPTIONS outputs
The OPTIONS method outputs are:
Error any - $.error
PATCH outputs
The PATCH method outputs are:
Error any - $.error

POST outputs
The POST method outputs are:
Error any - $.error
PUT outputs
The PUT method outputs are:
Error any - $.error
For how-to information on accessing Microsoft OneDrive using a REST flow-node, refer to Access Microsoft
OneDrive using a REST flow-node.
Set Context flow-node

The Set Context flow-node method, parameter, and output are described in the following sections.
Method
The method for a Set Context flow-node is:
• setContext
Parameter
The Set Context flow-node parameter is described in the following section.

setContext parameter
The setContext method parameter is:

selection
value any - - Selector, String,

Number, Boolean,
Object, Array, Null
Output
The Set Context flow-node output is described in the following section.
setContext output
The setContext method output is:
next any - -
Swagger flow-node
Overview
The Swagger plugin, @axway/api-builder-plugin-fn-swagger, loads Swagger documents from
the ./swagger folder in your application and generates one Swagger flow-node per Swagger document.
The generated Swagger flow-nodes expose methods that can be used within API Builder flows for
communication with the API services described in your Swagger documents.
The Swagger plugin is installed as part of the default API Builder project; however, if you need to manually
install it for some reason, navigate to your application folder and execute the following command:
npm install --no-optional @axway/api-builder-plugin-fn-swagger
For additional getting started information, refer to the API Builder Getting Started Guide.
Using the Swagger plugin

During the npm install, the Swagger plugin will create the ./swagger folder in the root directory of your
application. If the ./swagger folder already exists, it will be preserved with all of its content. To use the
Swagger plugin:
1. Place your Swagger files (in JSON or YAML format) into the ./swagger folder.
2. Place your service icons into the ./swagger folder. This is optional but highly recommended to make
your flows more readable. The icons must have the same name as the Swagger files for your service.
Additionally, the icons must be one of the following file formats: bmp, jpeg, jpg, png, gif, tiff, or
svg

3. Execute npm start to start your application. The Swagger flow-nodes will be available in the Connector
section of the flow-node list on the left side of the API Orchestration user interface. You should see a
plugin listed for each Swagger file successfully loaded from your ./swagger folder.
For example, here are the nodes for a service that has two Swagger documents, gmail.json and
petstore.yaml. For the Gmail Swagger, we have included a PNG icon file. Swagger Petstore is using the
default icon. For more information on using the Swagger plugin with Gmail, see Authorization: Access Gmail
using Swagger flow-node.
The flow-nodes generated for the Swagger service expose the methods that are defined in that Swagger
document. For example, here we have imported a Swagger for Gmail, and the available methods are the
APIs that the Swagger document describes.

The methods in the flow-nodes generated by the Swagger plugin expose all the parameters defined in the
Swagger document, their descriptions, and the schema definitions.


Here we have three outputs. All flow-nodes generated by the Swagger plugin will have at least Default and
Error outputs, with more being available if the provided Swagger document advertises additional known
status codes. In this case, the Swagger document advertises a known 200 status code for the API
corresponding to the gmail.users.messages.get method.
When executing the flow-node, if the Gmail service responds with a 200 status code, the 200 output will be
triggered. In the case that the service responded with any other status code, a Default will be triggered
allowing for alternative routing and inspection of the response data.
An Error will be triggered if the flow-node fails to make a request, for example, due to a timeout, or an
internal error occurs.
Each output will describe the type of response data and a more complex schema of the expected object
structure. In this case, 200 and Default both return a structure containing status, headers, and data. The
Error contains message and stack allowing for the error to be identified and tracked.

Authorization
As well as parameters, the Swagger document describes the Authorization requirements of an API. If a
Swagger flow-node requires authorization, the flow-node will expose that authorization as a parameter to
allow you to set the credential to use. For more information on how authorization is defined in Swagger, see
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#security-requirement-object.
The Swagger flow-node supports API Key, HTTP Basic, and OAuth 2.0 credentials.
For example, this Swagger document is defining an OAuth 2.0 security definition in the section
securityDefinitions which it is named Oauth2. Subsequently, in the method definitions, the Oauth2
security definition is specified as a requirement.

swagger/gmail.json Expand source

...
"Oauth2": {
"authorizationUrl": "https://accounts.google.com/o/oauth2/auth",
"scopes": {
email",
"https://www.googleapis.com/auth/gmail.compose": "Manage drafts and
send emails",
"https://www.googleapis.com/auth/gmail.insert": "Insert mail into your
mailbox",
"https://www.googleapis.com/auth/gmail.labels": "Manage mailbox
labels",
"https://www.googleapis.com/auth/gmail.metadata": "View your email
message metadata such as labels and headers, but not the email body",
"https://www.googleapis.com/auth/gmail.modify": "View and modify but
not delete your email",
messages and settings",
"https://www.googleapis.com/auth/gmail.send": "Send email on your
behalf",
"https://www.googleapis.com/auth/gmail.settings.basic": "Manage your
basic mail settings",
"https://www.googleapis.com/auth/gmail.settings.sharing": "Manage your
sensitive mail settings, including who can manage your mail"
},
"type": "oauth2"
}
},
...
"paths": {
...
"/{userId}/messages/{id}": {
"get": {
"operationId": "gmail.users.messages.get",
"security": [
{ "Oauth2": [ "https://mail.google.com/" ] },
{ "Oauth2": [ "https://www.googleapis.com/auth/gmail.metadata" ] },
{ "Oauth2": [ "https://www.googleapis.com/auth/gmail.modify" ] },
{ "Oauth2": [ "https://www.googleapis.com/auth/gmail.readonly" ] }
],
...
},
...
}
...
The flow node in API Builder reflects this as an authorization parameter named Oauth2 in the parameters
panel:

This parameter can be a Selector, a String, or a Credential. The Selector and String options
allow you to get the credential from an external source, for example, the credential could be read from a
header on the incoming request or it could be read from some external vault or database. The
Credential option tells API Builder to read the credential from its internal credential store.
To simplify populating the credential store with suitable credentials, the Swagger plugin will automatically
generate stub credentials when loading new Swagger documents. For more information, see Authorization
in Swagger Plugin. For more information on credentials, see API Builder Credentials.
Configure the Swagger plugin

In some scenarios, you may need to override the information in the Swagger document. For example, to
connect to staging servers rather than production ones while in testing.
When a new Swagger document is loaded a default configuration file is created for it in the conf folder of
your project.
conf/gmail.default.js Expand source

module.exports = {
// The configuration settings for your Swagger service.
pluginConfig: {
'@axway/api-builder-plugin-fn-swagger': {
'gmail': {
// It is possible to override Swagger URI
options when constructing
// outbound requests from the Swagger plugin.
uri: {
// protocol: 'https',
// host: 'hostname',
// port: 443,
// basePath: '/api'
}
}
}
},
// The following authorization credentials needed to use the Swagger

service.
// Please follow this guide to manually configure the credentials:
authorization.html
authorization: {
credentials: {
'Gmail Oauth2': {
...
}
}
}
};
Configure endpoint URI
You can configure endpoint URI in the generated configuration file for your Swagger.
To configure the endpoint URI, set the following parameter:
• uri - If this parameter is set, the plugin module will override the predefined endpoint URI.
Additionally, you can set the port, host, protocol, and base path as described in the following table.
Configuration parameters Description
uri.protocol The application protocol to use. For example: http

or https
uri.host The server name.
uri.port The port on which the host system listens for

requests. This parameter is optional. If a port is not
specified, the default port will be set depending on
the protocol.
uri.basePath The path to the API.
Accept and Content-Type

Starting from version 2.3.0 the Swagger plugin respects the `consumes` and `produces` properties in
Swagger documents. It is parsing this information and generates Advanced HTTP Options based on it.
More specifically:
• Content-Type is created based on the information in "consumes". This parameter is only available for
methods that have a body or formData payload.
• Accept is created based on the information in "produces".

Selecting default mime-type
Here are some rules regarding how the system chooses the mime-type that will be set to Content-Type and
Accept headers as part of the underlying HTTP request:
For Accept (always) and for Content-Type where methods have a body payload:
• If there are no valid mime-types in consumes/produces the default mime-type used is application/
json (this is for backward compatibility)
• If there is only one type specified in the consumes/produces property it is used by default
• If there are more mime-types the prioritization of selecting the default type is the following order:
1. application/json
2. Types ending with +json
3. The first valid type
For Content-Type where methods have formData parameters:
• If there are no valid mime-types in consumes:

• If the method has file parameters, the default mime-type is multipart/form-data
• If the method does not have file type parameters, the default mime-type is application/x-www-
form-urlencoded
• If there are valid mime-types in consumes:
• If there are file type parameters, use multipart/form-data if it exists; otherwise,
use application/x-www-form-urlencoded or the first valid type
• If there are no file type parameters, use application/x-www-form-urlencoded if it exists;
otherwise, use multipart/form-data or the first valid type
Overriding the default selection
The system offers the possibility to override the default selection.
If there are types specified in Swagger the user can select the desired type from the drop-down:

If there is no consumes/produces information specified in Swagger, the system shows an input field rather
than a drop-down, and the user can specify the value that they want to use:
Warning: Although version 2.3.0 introduces more flexibility in respect to content types it still does not allow
to completely skip sending the Content-Type and Accept HTTP headers. This is a known issue
and will be fixed in a future version of the plugin.
Filtering invalid types
According to RFC-7321, the "

Internet media types ought to be registered with IANA according to the procedures defined in ..." - So, if
the Swagger document contains invalid content types, the system will filter those types and will not show
them in the UI. A package called content-type is used under the hood to verify the validity of the content
type. It does not check if the type is registered in the IANA registry but check about the validity of its name.
In other words, a type named 'application/jsonsssss' will not be filtered but a type called 'banana' will be
filtered and not shown in the UI.

Decoding Response
Starting from version 2.3.0 the user has the option to configure the response format. For backward
compatibility, by default, the system applies the best effort to decode according to the content types
specified. If set to binary Node.js Buffer is returned for further processing in the Flow.
Swagger flow-node.
Axway Flow SDK

The Axway Flow SDK feature and functionally has been replaced by API Builder SDK.
The Axway Flow SDK (axway-flow-sdk) is a standalone utility that enables the creation of custom flow-
node plugins for API Builder flows. By offering the Axway Flow SDK as a standalone utility, new flow-nodes
can be developed and consumed in API Builder without upgrading the version.
Features
The Axway Flow SDK has the following content:
• CLI tool for starting a new flow-node plugin

• SDK for building custom modules for API Builder flows
Install
The following command installs the Axway Flow SDK.
npm install -g axway-flow-sdk

Use the Axway Flow SDK

The following generates a new flow-node plugin in the current directory. You can customize the plugin to
meet your requirements.
axway-flow -n <node name>

cd <node name>
npm run build
Alternatively, you can use npx to generate a flow-node plugin without installing axway-flow globally.
npx axway-flow -n <node name>

cd <node name>
npm run build
The generated plugin name is prefixed with the required api-builder-plugin- prefix.
The starter project is heavily commented to simplify the process of customizing it. It also comes with the
eslint configuration and the mocha unit tests incorporated to help you ensure the quality of your custom
flow-node.
encodeURI example
const sdk = require('axway-flow-sdk');
function getFlowNodes() {
const flownodes = sdk.init(module)
.add('encodeURI', {
name: 'Encode URI',
icon: 'encode.svg',
description: 'URI encoder'
})
.method('encode', {
name: 'Encode URI',
description: 'Encodes a URI by replacing each instance
of certain characters with UTF-8 encodings.'
})
.parameter('uri', {
type: 'string',
description: 'The URI to encode.'
})
.output('encoded', {
name: 'Encoded',
description: 'The encoded URI.',
context: '$.encodedURI',
schema: {
type: 'string'
}
})
.action((req, cb) => {
cb.encoded(null, encodeURI(req.params.uri));
});
return Promise.resolve(flownodes);

exports = module.exports = getFlowNodes;
Note that the encodeURI example is returning a function, getFlowNodes, that returns a promise. This
allows for the generation of the flow-node to be asynchronous, for example, to allow the loading of content
from a remote source. In this example, it is used for demonstration purposes only, flownodes could have
been returned from getFlowNodes instead.
Type references
In Axway API Builder, it is possible to reference other types. For example, types can be loaded from ./
schemas, registered from Models, or registered from plugins. Any registered schema can be referenced
whenever a schema is required.
.parameter('greeting', {
"$ref": "schema://model/appc.arrowdb/user"
})
.output('next', {
schema: {
}
})
Unit test your flow-node plugin

The starter project includes automatically generated unit tests in the ./test directory of your project. The
tests are, for example, purposes and will need to be customized to your specific use case. The SDK provides
a mocknode that allows for mock invocations of your flow-nodes methods.
mocknode (flow-nodes)
Mocks an API Builder flow-node using the flow-node generated with NodeBuilder.
Access: public
Parameter Type Description
flownodes NodeBuilder The NodeBuilder object.
Testing a successful output callback
This example uses mocha and promises to check that the flow-node is defined well enough to pass the
argument foo to the method method. It also mocks the callback using the defined output of the flow-
node and ensures that the method invokes the correct callback.
Note if the flow-node is asynchronous; in other words, returns a promise, the promise must be resolved to
get the flow-nodes defined in the plugin. This can be done using a before block that waits for the resolved
promise.
const flownodesPromise = require('../src');

const { mocknode } = require('axway-flow-sdk');
let flownodes;

before(() => {
return flownodesPromise.then((resolvedFlownodes) => {
flownodes = resolvedFlownodes;
});
});
it('describes a test', () => {

const args = { foo: undefined };
return mocknode(flownodes).node('example').invoke('method', args)
.then((response) => {
expect(response).to.deep.equal({
next: [null, 'stuff']
})
});
})
Testing an error default callback
This example is similar to the previous example, save that the expectation is that the method will invoke
cb('invalid argument') when given an undefined parameter.
const flownodes = require('../src');

const { mocknode } = require('axway-flow-sdk');
it('describes a test', () => {

const args = { foo: undefined };
return mocknode(flownodes).node('example').invoke('method', args)
.then((response) => {
expect(response).to.deep.equal(['invalid argument'])
});
})
Local API Builder test

While unit testing is important, it is also necessary to be able to install the custom flow-node plugin into your
local API Builder application for testing. This can be achieved by packing the module locally:
cd api-builder-plugin-fn-encodeuri
npm run build
npm pack
This will create a tgz archive (api-builder-plugin-fn-encodeuri-1.0.0.tgz) that can then be

installed into your API Builder application.
cd <app-folder>
npm install --no-optional <path to flow node project>/api-builder-plugin-
encodeuri-1.0.0.tgz
npm start
Type references
In Axway API Builder, it is possible to reference other types. For example, types can be loaded from ./
schemas, registered from models, or registered from plugins. Any registered schema can be referenced
whenever a schema is required.

"$ref": "schema://model/mongo/user"
})
.output('next', {
schema: {
"$ref": "schema://model/mongo/user"
}
})
API Reference
axway-flow-sdk~NodeBuilder
Kind: Inner class of axway-flow-sdk
• NodeBuilder
• .new NodeBuilder(srcModule, [options])
• .add(key, [options])
• .method(key, [options])
• .nodeBuilder.group(name)
• .parameter(name, schema, [required])
• .output(key)
• .action(handler)
new NodeBuilder(srcModule, [options])
Parameter Type Default Description
srcModule object A node module.
[options] object The options for the

builder.
[options.validate] object true Enables parameter

validation. Disable if you
need to use refs.
nodeBuilder.add(key, [options])
Adds a new flow-node spec and prepares the NodeBuilder to accept the following specification
operations:
• .output(key, [options])
The key parameter is used to uniquely identify the specification and represents a distinct instance of a flow-
node for the flow editor. The key is used as the name unless the name option is provided. The new flow-
node will appear in the general category by default, or under the provided category option.

The icon option can be a bmp, jpeg, png, gif, tiff, or svg file. The .method option is used to add a method
or methods, and the .output option is used to define an output. The .action option is used to define an
action function and finish the specification.
Kind: Instance method of NodeBuilder
Returns: Current NodeBuilder object
Access: Public
key string A unique key identifier

for the flow-node.
[options] object Options for the flow-

node.
[options.name] string A friendly name for the

flow-node as it will
appear in the UI.
[options.icon] string An icon file.
[options.description] string A description for the

flow-node.
[options.category] string general A category under which

the flow-node will
appear in the UI.
Example:
sdk.init(module).add('encodeURI', { icon: 'encode.svg' });
nodeBuilder.method(key, [options])
Adds a new method to the current flow-node specification and prepares the NodeBuilder to accept the
following method operations:

The .add(key, [options]) must be called before adding a method.
The key uniquely identifies the method for the flow-node and will be used as the name unless the name
option is provided.
Access: Public

key string A unique key identifier for the

method.
[options] object Options for the method.
[options.name] string A friendly name for the method

as it will appear in the UI.
[options.description] string A description of the method.
Example:
sdk.init(module).add('encodeURI', { icon: 'encode.svg' })

.method('encode', { name: 'Encode URI' });
Example (Disable validation):
sdk.init(module, { validation: false }).add('encodeURI', { icon:

'encode.svg' })
.method('encode', { $ref: '#/definitions/foo' });
nodeBuilder.group(name)
Access: Public
name string A unique name for the parameter

group as it will appear in the UI.

.method('encode', { name: 'Encode URI' })
.group('Advanced')
.parameter('uri', { type: 'string' });
nodeBuilder.parameter(name, schema, [required])
Adds a new parameter to the current method. Any number of parameters can be added to a method.
The .method(key, [options]) must be called before adding a parameter.
The name uniquely identifies the parameter, and the schema is a valid JSON Schema definition (both
draft-04 and draft-06 are supported).

Access: Public
name string A unique name for the

parameter as it will
appear in the UI.
schema object A schema used to

validate the parameter.
[required] boolean true A flag to indicate the

parameter is required or
optional.
Example:

nodeBuilder.output(key)
Adds a new output to the current method. Any number of outputs can be added to a method, but for
usability-sake, you should limit this. The output represents one of the possible callback routes for your
method. For example, if your method tested prime numbers, then one output might be prime, and the other
not-prime.
The .method(key, [options]) must be called before adding an output.
The key uniquely identifies the output route. The schema is a valid JSON Schema definition (both draft-04
and draft-06 are supported). If a schema is not provided, then the output type is effectively any type.
The context is a valid JSON Path and is used as the default by the flow editor. When the output is invoked,
the configured context is where the output value will be written.
Access: Public
key string A unique key for the output.
[options.name] string A friendly name for the output as

it will appear in the UI.
[options.description] string The output description.
[options.context] string The default context string.

[options.schema] object The expected JSON schema for

the output value.
Example:

.parameter('uri', { type: 'string' })
.output('encoded', { context: '$.encodedURI', schema: { type:
'string' } });
nodeBuilder.action(handler)
Assigns an action handler to the current method. The method can only have one action handler. Assigning
an action will terminate the current method definition.
Access: Public
handler handler The action handler function.
Example:

.output('encoded', { context: '$.encodedURI', schema: { type: 'string' } })
.action((req, cb) => cb.encoded(null, encodeURI(req.params.uri));
axway-flow-sdk~init(module)
Axway API Builder SDK for creating custom flow-nodes to work with flows.
Kind: Inner method of axway-flow-sdk
Returns: NodeBuilder - A newly constructed NodeBuilder object
module object The flow-node module.
Example:
const sdk = require('axway-node-sdk');

exports = module.exports = sdk.init(module);
axway-flow-sdk~validate(nodes)
Validates the flow-nodes against the Axway Flow schema.

Kind: Inner method of axway-flow-sdk
Throws: Error - If nodes contain invalid flow-nodes.
nodes NodeBuilder Nodes to validate.
Example:
const nodes = sdk.init(module).add('encodeURI', { icon: 'encode.svg' })

'string' } })
sdk.validate(nodes);
API Builder Models

Introduction
This guide covers the basic instructions for creating Models. Models are data stored in either server
memory or a backend service, such as a MySQL database, using an API Builder Connector. Models are
accessed like standard REST objects using predefined endpoints that API Builder automatically generates
by default. You can either create a model by defining your schema, use an existing model defined by a
connector, modify an existing model by either extending or reducing it, or create a composite model by
joining two or more models together.
Model definition
Place all Model files in the models folder. You can only declare one model per file. A Model file is a

2. Calls the module's createModel(name, schema) method (or another Model method), passing in the
name of the model as the first parameter and an object defining the model schema as the second
parameter.
Set the following keys in the object passed to the createModel() method to define the model:
fields true An object that represents the

model’s schema defined as key-
value pairs. The key is the name
of the field, and the value is

the fields object. See the next

table for details.
connector true Connector to which the model is

bound (string). Each model can
only have one connector.
Connectors are responsible for
reading and writing data from/to
their data sources.
Field definition
The fields property (mentioned above) supports several sub-properties as well. The table below outlines
these properties.
type true The field primitive type plus

others, for example, string,
number, boolean, object,
array, and date). Type can be
any valid JavaScript primitive
type. Type can be specified as a
string (for example, string) or
by the type class (for example,
String).
required false Specifies whether the field is

required. The default value
is false.
validator false A function or regular expression

that validates the value of the
field. The function is passed the
data to validate and should
return either
null or undefined if the
validation succeeds. Any other
return value means the validation
failed, and the return value will be
used in the exception message. If
a regular expression is used, it
should evaluate to either true or
false.
name false Used if the model field name is

different than the field name in
the connector’s model or the
underlying data source for the
field name. For example, if my

model field is first_name and

the column in a MySQL database
is fname, the value of
the name property should be
fname.
default false The default value for the field.
description false The description of the field (used

for API documentation).
readonly false Either true or false. If true,

the field will be read-only and any
attempt to write the field value
will fail.
maxlength false The max length of the field

(specified as an integer)
get false A function used to set the value

of a property that will be sent to
the client. This property is useful
if you want to define a custom
field where the value is derived.
set false A function used to set the value

the connector.
custom false This property should be specified

and set to true if you are
defining a custom field. A custom
field is one that does not exist in
the underlying data source for the
connector you specified.
model false The model name of the field

property. This is either the logical
name of a custom model or a
connector model name in the
form connector/model_name (for
example, memory/employee).
Model schema example
The example below creates the car model with the specified schema. The car models will be stored in
Mobile Backend Services as CustomObjects. Since the autogen property was not set to false, API Builder
automatically generates the pre-defined endpoints for the client to access the car models using
the <SEVER_ADDRESS>/ api/car endpoints.


var User = APIBuilder.Model.extend('testuser', {
fields: {
first_name: { type: String },
last_name: { type: String },
email: { type: String }
},
connector: 'memory'
});
module.exports = User;
Modify an existing model

Besides creating a fully defined model, you can modify an existing model either by reducing or extending it.
Reduce a model
A reduced model is an existing model where you only use specific fields from it. To create a reduced model,
follow the same procedure when creating a regular model, except invoke the module's Model.reduce()
method instead of the createModel() method. Pass the model you want to reduce as the first parameter,
the name of the new model as the second parameter, and the new model schema as the last parameter.
Example
The Model file below extracts three fields from the employee table of the memory connector, indicated by
the memory/employee parameter, and renames the fields for the baseEmp model, for
example, email_address in the MySQL employee table maps to email in the new model.
models/baseemp.js
var baseEmp = APIBuilder.Model.reduce('memory/employee','baseEmp',{

fields: {
fname: {type:String, description:'First name', required:true,
name:'first_name'},
lname: {type:String, description:'Last name', required:true,
name:'last_name'},
email: {type:String, description:'Email address', required:true,
name:'email_address'}
}
});
module.exports = baseEmp;
Extend a model
An extended model is an existing model where you modify the fields or add more fields. To create an
extended model, follow the same procedure when creating a regular model, except invoke the
module's Model.extend() method instead of the createModel() method. Pass the model you want to
extend as the first parameter, the name of the new model as the second parameter, and the new model
schema as the last parameter.
Example
The Model below extends the employee model by adding the headquarters field to it.

models/fullemp.js
var fullEmp = APIBuilder.Model.extend('employee','fullEmp',{

fields: {
headquarters:{type:Boolean, custom:true,
get:function(val,key,model){
return model.get('state') === 'CA';
}
}
}
});
module.exports = fullEmp;
Create a composite model

Composite models allow you to create a single model that is composed of one or more models based on
the same or different connectors. Composite models can be joined together via a common set of
properties, such as primary keys or foreign keys, or they can have no properties in common at all. The power
of composite models is that you can represent multiple data sources and entities as a single API endpoint,
which is ideal for many mobile use cases.
To create a composite model, follow the same procedure when creating a regular model except the
connector property must be set to composite, each field in the definition object must specify the model
property to indicate which model the field originates from, and the metadata property must define the join
operation to combine the models or leave it undefined to perform no join operations.
The following terms are used to refer to models:
• Model definition: The composite model which is being created

• Main model: The main source of data for the composite model. This is the left table in SQL
terminology. It is implicitly defined.
• Secondary model: Any model other than the main model. This will be the right table in SQL
terminology.
The composite connector can either perform a left join or inner join:
• left join: all records from the main model are returned regardless if it found a match in the secondary
models
• inner join: only records that match both models are returned
The composite connector can also perform either a one-to-one join or one-to-many join:
• one-to-one: only one record from the secondary model matches a record in the main model
• one-to-many: multiple records from the secondary model match a record in the main model
There are different ways that a one-to-one join and a one-to-many join can work when merging (mapping)
data from the secondary model into the main model:
• Merge as object: This is a one-to-one relationship where the whole secondary model record will be
mapped to a field in the main model.

• Merge as an array: This is a one-to-many relation where multiple records from the secondary model
will be mapped to an array field in the model definition.
• Merge as a field: This is a field that comes directly from a joined model. The field in the model
definition must have a name property that refers to the field being joined from the secondary model.
By default, this is a one-to-one relationship where the field will contain a single match. In the Join-
Object Definition, multiple may be set to true for all of the matches to be mapped to the field. Since
this returns multiple values, the field type must be Array if multiple is set to true.
The composite connector can be used to perform "reduce" functionality on a single model. This only
requires the main model and does not require any joins. The API Builder Console offers its functionality
using this method. Without any joins, a one-to-one merge as a field is the only functionality available.
To define the join operation, set the metadata property to the left_join key or inner_join key, either
of which takes an array of objects defining the join. Each object in the left_join or inner_join property
defines the model to join (model property), the key to join (join_properties property) and, optionally, if
the join is a multiple property.
Join object definition
Key Type Value
model String Name of the model. For left joins,

this is the secondary model you
want to join with the main model.
join_properties Object Collection of key-value pairs that

determine the keys in each model
to perform the join operation. The
key is the property of the model
defined in this object, and the
value is the property to join in
another model (or the main
model for left joins).
multiple Boolean Determines whether the match is

one-to-one (false) or one-to-many
(true). The default value is
false. If true, the field being
joined on must be of type Array
and have a name property
referring to the field from the
secondary model to be used.
Left join example
The example below combines the employee and managers models to create the
employee_manager model. The models are joined based on a match between the manager's model
employee_id and the employee model's auto-generated id.
models/employee_manager.js
var employee_manager = APIBuilder.createModel('employee_manager',{

fields: {
fname: {type:String, description:'First name', name:'fname',
model:'employee'},
manager: {type:String, description:'manager of employee', name:
'manager', model:'managers'}
},
connector: 'composite',
metadata: {
left_join: {
model: 'managers',
join_properties: {
employee_id: 'id'
}
}
}
});
module.exports = employee_manager;
models/employee.js
var employee = APIBuilder.Model.reduce('memory/employee','employee',{

fields: {
fname: {type:String, description:'First name', name:'first_name'}
},
connector: memory'
});
module.exports = employee;
models/managers.js
var managers = APIBuilder.Model.reduce('memory/employee_manager','managers',{

fields: {
employee_id: { type: Number, description: 'Employee ID' },
manager: {type:String, name:'manager_name', description:'manager name'}
},
connector: 'memory'
});
module.exports = managers;
Inner join example
The example below performs an inner join on the employee, employee_manager and employee_habit
models. Both the employee_manager and employee_habit employee_id properties will try to match
the employee id property. The description of every habit which matches the employee ID will be listed in
the habit property.
Expand source
// create a model from a mysql table

var employee_composite = APIBuilder.createModel('employee_composite',{

fields: {
fname: {type: String, description: 'First name', name: 'fname', model:
'employee'},
manager: {type: String, description: 'Manager of employee', name:
'manager', model: 'employee_manager'},
habits: {type: Array, description: 'Habits of employee', name:
'description', model: 'employee_habit'}
},
metadata: {
inner_join: [
{
model: 'employee_manager',
join_properties: {
employee_id: 'id'
}
},
{
model:'employee_habit',
multiple: true,
join_properties:{
employee_id:'id'
}
}
]
}
});
module.exports = employee_composite;
Field name mappings

You often want the ability to use a field property name in your model that is different from its name in an
existing model. The following example shows how you can use the name sub-property of a field to map a
model property name to a specific property name of an existing custom model or connector generated
model. For example, the employee model has a property called first_name, but the new model wants that
property to be called fname. The API Builder framework ensures this mapping occurs bidirectionally.
var emp = APIBuilder.Model.reduce('memory/employee','emp',{

fields: {
fname: { type:String, description:'First name', name:'first_name',
required:true},
lname: { type:String, description:'Last name', required:true,
name:'last_name'},
email: { type:String, description:'Email address', readonly:true,
},
connector: 'memory'
});
module.exports = emp;

Field input validation

You might need to perform validation on a field when creating or updating a record. Each property in your
model definition can specify a validation function using the validator field property. This function is
called before sending data to your model’s connector. The validator function is passed the value of the
property. If the value is valid, the function should return null or undefined. If not valid, the function
should return a message indicating why the validation failed. The following is an example of a validator
function on a field.

fields: {
fname: {
type:String, description:'First name', name:'first_name',
required:true,
validator:function(val) {
if (val.length < 5) {
return 'First name must be greater than 5 characters'
}
}
},
name:'last_name'},
},
connector: 'memory'
});
Model input validation

You might need to perform validation on a whole model. Specify in your model definition a validation
function using the validator model property. This function is called before sending data to your model’s
connector. The validator function is passed the instance of the model. If the value is valid, the function
should return null or undefined. If not valid, the function should return a message indicating why the
validation failed or throw an exception. The following is an example of a validator function on a model.

fields: {
fame: { type:String },
lname: { type:String }
},
validator: function (instance) {
var errors = [];
if (instance.get('fame') === "Rick") {
errors.push('Sorry, Rick is not allowed to play here.');
}
if (instance.get('lname').length < 5) {
errors.push('The lname must be at least 5 characters long.');

}
if (errors.length) {
return errors.join('\n');
}
},
connector: 'memory'
});
Customizing generated model APIs

You can customize the generated APIs for your models. For example, by default, the create API only returns
a status 201 with a header Location pointing to the newly created instance. No content body is returned. If
you want to directly receive the newly created instance in the body of the request, add
the includeResponseBody: true metadata to your model.

fields: {
fname: {
type:String, description:'First name', name:'first_name',
required:true
},
name:'last_name'},
},
connector: 'memory',
metadata: {
includeResponseBody: true
}
});
Programmatic CRUD interface

All models inherit the CRUD interfaces supported by their underlying connector. As a result, you can
programmatically call these interfaces. The main use case for using a model’s CRUD interface is when you
want more control of an API's functionality. You can place logic in your API endpoint’s action function to
handle custom business functionality and control the execution of data access.
The following are the main interfaces most connectors support.
// delete all records for a model

Model.deleteAll(callback);
// query a model.
Model.query(options, callback);
// find all records for a model

Model.findAll(callback);
// find a record by id for a model

Model.findByID(id, callback);
// delete a record for a model

Model.delete(instance, callback);
// update a record
Model.update(instance, callback);
// create a record
Model.create(object, callback);
The following model has example uses.
// example model
Model = APIBuilder.Model.extend(testTableName, {
fields: {
title: { type: String },
content: { type: String }
},
connector: 'memory'
});
Delete all records
Use the deleteAll function on a model to delete all of its records.
Model.deleteAll(function(err) {
if (err) {
return next(err);
}
next();
});
Create, update, delete a record
The following is an example of creating a record and then updating and deleting it. It’s not necessarily a
practical example but demonstrates how to use some additional interfaces available on a model.
Expand source
// setup record object
var title = 'Test',
content = 'Hello world',
object = {
title: title,
content: content
};
// create record then update then delete

Model.create(object, function(err, instance) {
if (err) {
// do something
}

// update instance
instance.set('content', 'foo');
// save instance
instance.update(function(err, result){
// logic here
});
// delete instance
instance.delete(function(err,result){
// logic here
});
});
Run a query
The following is a simple example of performing a query against a model.
// setup query options

var options = {
where: { content: { $like: 'Hello%' } },
sel: { content: 1 },
order: { title: -1, content: 1 },
limit: 3,
skip: 0
};
// execute query
Model.query(options, function(err, coll) {
// process results
});
If none of these values are present in options , the options object is treated as a where statement.
// setup query options

var options = {
content: { $like: 'Hello%' }
};
// execute query
Model.query(options, function(err, coll) {
// process results
});
Restricting CRUD endpoints

By default, models support the basic CRUD methods (CREATE, READ, UPDATE, and DELETE). You can limit
the methods supported by a model by using the actions property.

fields: {
fname: { type:String, description:'First name', name:'first_name',
required:true},


name:'last_name'},
email: { type:String, description:'Email address', required:true,
},
actions:['create','read'],
connector: 'memory'
});
In this example, the model only allows create (POST) or read (GET). DELETE and PUT are not allowed and
would fail.
The valid values for the action property are: create, read, update, delete, and deleteAll.
Predefined or custom endpoints

By default, API Builder generates the following API endpoints for models:
• GET /api/<model_name> : Return all objects (the first 1000 records).

• GET /api/<model_name>/query : Return all objects that satisfy a query.
• GET /api/<model_name>/:id : Return a specific object by id
• GET /api/<model_name>/distinct : Find distinct objects
• GET /api/<model_name>/count : Count objects
• PUT /api/<model_name>/:id : Update a specific user by id
• PUT /api/<model_name>/findAndModify : Find and modify an object
• POST /api/<model_name> : Create a new object
• POST /api/<model_name>/upsert : Create or update an object
• DELETE /api/<model_name>/:id : Delete a specific object by id
• DELETE /api/<model_name> : Delete all objects
To disable API Builder from generating these endpoints, set the Model's autogen property to false when
defining the model. You will need to create API Builder API objects to access the model.
Example
The following model disabled generating pre-defined endpoints. An API endpoint needs to be defined to
access the model data, as shown below.
models/employee.js
var employee = createModel('employee', {

fields: {
first_name: {type:String, description:'First name', required:true},
last_name: {type:String, description:'Last name', required:true},
email_address: {type:String, description:'Email address',
required:true}
},

autogen: false
});
The example below implements the GET /api/<employee>/:id endpoint that would normally be
generated by API Builder.
apis/employeefindById.js
var findEmployeeById = APIBuilder.API.extend({

group: 'employeeAPIs',
path: '/api/employee/:id',
method: 'GET',
description: 'This API finds one employee record',
model: 'employee',
parameters: {
id: {description: 'the employee id'}
},
}
});
module.exports = findEmployeeById;
Models - Access a Model

Any callback in the application that is passed the request object can access the Models programmatically.
If the actions property in the model definition is set, some of the methods cannot be invoked.
The actions property restricts which CRUD operations can be invoked on the models.
1. Retrieve an instance to API Builder using the request.server property.

2. Retrieve the Model instance using API Builder's getModel (name) method by passing it the name of
the model.
3. Invoke one of the following methods on the Model instance and pass it a callback function, which is
passed an error and results object:
a. create(object, callback): Creates a model.
b. query(options, callback): Retrieves models specified by the query.
c. findAll(callback): Retrieves all models.
d. findById(id, callback): Retrieves the model specified by the id parameter.
e. update(instance, callback): Updates the passed model.
f. deleteAll(callback): Deletes all models.
g. delete(instance, callback): Deletes the passed model.
Models - Composite

Create a composite model

Composite models allow you to create a single model that is composed of two or more models based on
the same or different connectors. Composite models can be joined together via a common set of
properties, such as primary keys or foreign keys, or they can have no properties in common at all. The power
of composite models is that you can represent multiple data sources and entities as a single API endpoint,
which is ideal for many mobile use cases.
To create a composite model, follow the same procedure when creating a regular model except
the connector property must be set to composite, each field in the definition object must specify
the model property to indicate which model the field originates from, and the metadata property must define
the join operation to combine the models or leave it undefined to perform no join operations.
The composite connector can either perform a left join or inner join:
• left join: all records from the main model are returned regardless if it found a match in the secondary
models
• inner join: only records that match both models are returned
The composite connector can also perform either a one-to-one join or one-to-many join:
• one-to-one: only one record from the secondary model matches a record in the main model
• one-to-many: multiple records from the secondary model can match a record in the main model
To define the join operation, set the metadata property to either the left_join key or inner_join key,
either of which takes an array of objects defining the join. Each object in
the left_join or inner_join property defines the model to join (model property), a key to join
(join_properties property), and optionally if the join is one-to-one or one-to-many (multiple property).
Join object definition
Key Type Value
model String Name of the model. For left joins,

this is the secondary model you
want to join with the main model.
join_properties Object Collection of key-value pairs that

determine the keys in each model
to perform the join operation. The
key is the property of the model
defined in this object, and the
value is the property to join in
another model (or the main
model for left joins).
multiple Boolean Determines if the match is one-

to-one (false) or one-to-many
(true). The default value is
false.

Left join example
The example below combines the employee and managers models to create
the employee_manager model. The models are joined based on a match between the manager's model
employee_id and the employee model's auto-generated id.
models/employee_manager.js
var employee_manager = APIBuilder.createModel('employee_manager',{

fields: {
fname: {type:String, description:'First name', model:'employee'},
manager: {type:String, description:'manager of
employee',model:'managers'}
},
metadata: {
left_join: {
model: 'managers',
join_properties: {
employee_id: 'id'
}
}
}
});
module.exports = employee_manager;
models/employee.js
var employee = APIBuilder.Model.reduce('memory/employee','employee',{

fields: {
fname: {type:String, description:'First name', name:'first_name'}
},
connector: 'memory'
});
models/managers.js
var managers = APIBuilder.Model.reduce('memory/employee_manager','managers',{

fields: {
employee_id: { type: Number, description: 'Employee ID' },
manager: {type:String, name:'manager_name', description:'manager name'}
},
connector: 'memory'
});
module.exports = managers;

Inner join example
The example below performs an inner join on the employee,

employee_manager, and employee_habit models. Both
the employee_manager and employee_habit employee_id properties will try to match the
employee id property.
Expand source
// create a model from a mysql table

var employee_composite = APIBuilder.createModel('employee_composite',{
fields: {
fname: {type: String, description: 'First name', model: 'employee'},
manager: {type: String, description: 'Manager of employee', model:
'employee_manager'},
habit: {type: String, description: 'Habit of employee', model:
'employee_habit'}
},
metadata: {
inner_join: [
{
model: 'employee_manager',
join_properties: {
employee_id: 'id'
}
},
{
model:'employee_habit',
multiple:true,
join_properties:{
employee_id:'id'
}
}
]
}
});
module.exports = employee_composite;
Models - Definition
Place all Model files in the models folder. You can only declare one model per file. A Model file is a

2. Calls the module's createModel (name, schema) method (or another Model method), passing in the
name of the model as the first parameter and an object defining the model schema as the second
parameter.

Set the following keys in the object passed to the createModel() method to define the model:
fields true An object that represents the

model’s schema defined as key-
value pairs. The key is the name
of the field, and the value is
the fields object. See the next
table for details.
connector true Connector to which the model is

bound (string). Each model can
only have one connector.
Connectors are responsible for
reading and writing data from/to
their data sources.
Field definition
The fields property (mentioned above) supports several sub-properties as well. The table below outlines
these properties.
type true The field primitive type plus

others (for example, string,
number, boolean, object,
array, and date). Type can be
any valid JavaScript primitive
type. Type can be specified as a
string (for example, string) or
by the type class (for example,
String).
required false Specifies whether the field is

required. The default value
is false.
validator false A function or regular expression

that validates the value of the
field. The function is passed the
data to validate and should
return either
null or undefined if the
validation succeeds. Any other
return value means the validation
failed, and the return value will be
used in the exception message. If
a regular expression is used, it

should evaluate to either true or

false.
name false Used if the model field name is

different than the field name in
the connector’s model or the
underlying data source for the
field name. For example, if my
model field is first_name and
the column in a MySQL database
is fname, the value of
the name property should be
fname.
default false The default value for the field.
description false The description of the field (used

for API documentation).
readonly false Either true or false. If true,

the field will be read-only and any
attempt to write the field value
will fail.
maxlength false The max length of the field

(specified as an integer)
get false A function used to set the value

the client. This property is useful
if you want to define a custom
field where the value is derived.
set false A function used to set the value

the connector.
custom false This property should be specified

and set to true if you are
defining a custom field. A custom
field is one that does not exist in
the underlying data source for the
connector you specified.
model false The model name of the field

property. This is either the logical
name of a custom model or a
connector model name in the
form connector/model_name (for
example, appc.mysql/employee).

Model schema example

The example below creates the car model with the specified schema.
var car = APIBuilder.createModel('car', {

fields: {
make:{type:String, description:'the make of a car '},
model:{type:String, description:'the model of the car', required:true},
year: {type:Number, description:'year the car was made',
required:true},
bluebook: {type:Number, description:'kelly bluebook value of the car',
required:true},
mileage: {type:Number, description:'current mileage of the car',
required:true}
},
connector: 'memory'
});
module.exports = car;
Models - Predefined or Custom Endpoints

By default, API Builder generates the following API endpoints for models:
• GET /api/endpoints/<model_name> : Return all objects (the first 1000 records).

• GET /api/endpoints/<model_name>/query : Return all objects that satisfy a query.
• GET /api/endpoints/<model_name>/:id : Return a specific object by ID.
• GET /api/endpoints/<model_name>/distinct : Find distinct objects.
• GET /api/endpoints/<model_name>/count : Count objects.
• PUT /api/endpoints/<model_name>/:id : Update a specific user by ID.
• PUT /api/endpoints/<model_name>/findAndModify : Find and modify an object.
• POST /api/endpoints/<model_name> : Create a new object.
• POST /api/endpoints/<model_name>/upsert : Create or update an object.
• DELETE /api/endpoints/<model_name>/:id : Delete a specific object by ID.
• DELETE /api/endpoints/<model_name> : Delete all objects.
To disable API Builder from generating these endpoints, set the Model's autogen property to false when
defining the model. You will need to create API Builder APIs to access the model.
Example:
The following model is disabled from generating pre-defined endpoints. An API endpoint needs to be
defined to access the model data as shown below.

modes/employee.js
var employee = createModel('employee', {

fields: {
first_name: {type:String, description:'First name', required:true},
last_name: {type:String, description:'Last name', required:true},
email_address: {type:String, description:'Email address',
required:true}
},
autogen: false
});
The example below implements the GET /api/<employee>/:id endpoint that would normally be
generated by API Builder.
apis/employeeFindOne.js
var employeeFindOne = APIBuilder.API.extend({

group: 'employeeAPIs',
path: '/api/employee/:id',
method: 'GET',
description: 'This API finds one employee record',
model: 'employee',
parameters: {
id: {description: 'the employee id'}
},
}
});
module.exports = employeeFindOne;
API Builder Plugins

API Builder 4.0.0 introduces the concept of plugins. Plugins are regular node modules that are included in
your API Builder project's package.json file.
API Builder detects plugins by searching for installed modules with the api-builder-plugin- prefix.
These plugins can contain a mixture of different component types.
• flow-nodes
• schemas
• data connectors

Plugins which are released by Axway can be categorized by an additional prefix based on the components
and functionality that they provide:
• flow-nodes: api-builder-plugin-fn-
• data connectors: api-builder-plugin-dc-
For information on the Connectors UI, refer to API Builder Console.
Configuration
Most plugins are configured using the pluginConfig key inside your application config. A lot of plugins
will generate a config file upon install which may look like this:
module.exports = {
pluginConfig: {
"api-builder-plugin-myplugin": {
// configuration goes here
}
}
}
When API Builder loads plugins, the configuration specific to each plugin (identified by name) will be
provided on load. Plugins may or may not require configuration, but common settings may include
authentication tokens/keys and other user-specific content.
Other plugins, such as api-builder-plugin-dc-, may use a slightly different or legacy method of
configuration. Check the readme of individual plugins for specific details.
Creating your own plugins

We provide a method to create shareable plugins that contain flow-nodes for orchestration within the flow
editor. For this, you can use the axway-flow-sdk.
Local plugins
There may be cases where you want to use a plugin in your project, which is not available publicly on NPM -
Possibly received in the form of a .tar.gz or developed locally.
NPM allows for local dependencies using the "file:" protocol, and as of NPM 5 will link file dependencies to
preserve disk space.
1. Extract and copy your plugin into any folder in your project, for example /plugins .
The folder that the plugin lives in must match its package name. In this case, the plugin is called api-
builder-plugin-myplugin.
2. Navigate to the root directory of your application and run the following command to install the plugin
as a local dependency.
npm install --no-optional plugins/api-builder-plugin-myplugin
Now, whenever you run an NPM install, the local plugin and its dependencies will be installed
alongside the rest of your app's dependencies and will be available in your project.

API Builder SDK

The API Builder SDK is a plugin SDK for implementing custom flow-nodes for API Builder flows.
Getting started
To get started with API Builder plugin development, use the @axway/api-builder CLI to generate a new
plugin project.
npx @axway/api-builder plugin init myplugin

cd api-builder-plugin-myplugin
npm install
npm test
That's it!
You have created your first API Builder plugin! The CLI generated an example flow-node called "Hello World"
that creates greeting based on the provided name. You can use this guide to modify it to create your custom
flow-node.
Using the plugin

The API Builder plugin is an npm module. To use the plugin, you must install the plugin as a dependency of
an existing API Builder project. If you do not have a project, refer to the API Builder Getting Started Guide.
There are several ways to install a plugin as a dependency (for a complete list see npm-install):
• from npm
• from a relative directory
• from within an API Builder project
Managing separate modules as dependencies requires a basic understanding of npm that is not covered by
this guide (see this guide for more information).
Install a plugin from npm
To install a plugin from npm as a dependency, it must first be published to npm (see npm-publish). Run the
npm install command to install the plugin as a dependency of an existing API Builder project. This is the
best way to manage plugin dependencies.
cd my-existing-api-builder-project
npm install api-builder-plugin-myplugin
npm start
Install a plugin from a relative directory
Assuming your projects all share the same root folder, you can install the plugin directly from the source.
Note that this is going to create a copy of your plugin in the node_modules directory. So, if you modify your
plugin, then you will need to run the install command again (you can avoid this by using npm-link).
npm install ../api-builder-plugin-myplugin
npm start

Install a plugin from an API Builder project
It is possible to create and manage plugins directly from your API Builder project. It is very similar to
installing a plugin from a relative directory, but it has some advantages in that it will share the same source
as your project. However, like the relative directory, it still requires that you run npm install, but you will
only need to do this once because npm will create a link for you (see npm-link).
npm install ./api-builder-plugin-myplugin
npm start
Plugin contents
├───package.json
├───src/
│ ├───actions.js
│ ├───flow-nodes.yml
│ ├───icon.svg
│ ├───index.js
└───test/
└───test.js
Filename Description
package.json This is your module package description file. You

should modify it to suit your module.
src/actions.js This file contains the actual JavaScript

implementations of the methods defined in the
src/flow-nodes.yml file. You will add your
method implementations here.
src/flow-nodes.yml Defines your flow-node. You will modify to add your

flow-node and methods.
src/icon.svg The icon file that is used in the UI. Supports image
formats: bmp, jpeg, png, gif, tiff, or svg.
src/index.js Exports the API Builder plugin. You should not need
to modify this file.
test/test.js A mocha test suite. You should ensure all of your

actions are adequately tested.
Creating your flow-node

The API Builder plugin for flow-nodes is configured using a YAML file called flow-nodes.yaml within each
project. The flow-nodes.yaml file defines a structure that determines:
• The flow-node(s) to export.

• The method(s) that comprise each flow-node.
To get started, you can modify the example generated by the CLI.

JSON Schema
Flow-nodes utilize JSON schema to describe the acceptable values for various inputs and outputs. For
simple parameters, this might be one of the standard data types, for example, type: string.
Below are some example schema. Additional examples can be found here.
# The value must be a string. The standard types are:

# null, boolean, object, array, number, string
type: string
# The value should be a boolean. The `default` is documentation
# purposes only and has to be handled in code.
type: boolean
default: true
# The value must be string or null
oneOf:
- type: string
- type: null
# The value must be a string and either "foo" or "bar"
type: string
enum:
- foo
- bar
# The value must be string and match a regex pattern
type: string
pattern: "v[0-9]+"
# The value must be string and is a multiline input format.
# Formats with special UI: multiline, javascript, mustache
type: string
format: multiline
flow-node
The flow-nodes key is the top-most element in the flow-nodes.yml file. A flow-node specification
begins with a unique key beneath flow-nodes.
A flow-node is just a container for several related functions. Each flow-node will correlate to a single UI
element and icon that can be utilized within the API Builder flow editor. You can define multiple flow-nodes
in the same plugin project, but generally speaking, it is more advisable to have a single-purpose plugin that
defines one flow-node.
flow-nodes:
myplugin:
name: My Plugin
icon: icon.svg
description: My plugin is awesome.
category: general
methods:
# ...
flow-node attributes
The following table lists the attributes available when defining a flow-node:

Keyword Required Description
name no A friendly name for your flow-

node. This is how it will appear in
the UI. Defaults to the flow-node
key.
icon no An icon file for the UI. Supports

formats: bmp, jpeg, png, gif, tiff,
or svg. The file must be relative
to the flow-nodes.yml file.
The height and width of the icon
should be equal (for example,
around 80px). Using svg allows
the icon to scale cleanly.
description no A summary of what the flow-node

supports.
category no The category to which your flow-

node should belong. Defaults to
"general".
methods no A set of method definitions.
method
A method defines an operation, its input parameters, and its outputs. The method is identified by a unique
key below the flow-node methods attribute.
• Methods are sorted by name in the UI flow-node configuration panel.

• There is no limit to the number of methods.
• The method key correlates to an action in the actions.js file. If you rename the method in flow-
nodes.yml, you should also rename it in actions.js.
methods:
getSomething:
name: Gets something
description: Gets something from somewhere
parameters:
# ...
outputs:
# ...
method attributes
The following table lists the attributes available when defining a method.

name no A friendly name for your method.

This is how it will appear in the
UI. Defaults to the method key.
description yes A summary of the method.
parameters no A set of unique parameter

definitions.
outputs no A set of unique output

definitions.
parameter
A parameter defines an input to the method's action function. The parameter is identified by a unique key
below the method's parameters attribute.
The parameter key is used within the flow when setting/getting the parameter value. Typically, the
parameter key should be simple property identifiers (in other words, A-Z characters). Otherwise, it will be
difficult to use them within the flow.
• There is no limit to the number of method parameters that can be defined.

• In the flow-node configuration panel in the UI, parameters are sorted first by ungrouped parameters (in
other words, by parameters that do not define a group), then alphabetically by parameter group.
• Within each parameter group, parameters are sorted by required parameters first (required: true),
then alphabetically by parameter key.
parameters:
username:
name: Username
description: The user name.
required: true
initialType: string
schema:
type: string
parameter attributes
description no A description of the parameter.
required no Specifies that the parameter is

required. Defaults to true.
initialType no The initial type to display by

default in the UI flow-node
configuration panel for this
parameter. Allowed values are:
object, array, string,

selector, null, boolean and

number. The default is
selector.
group no A group name to which the

parameter belongs, for example,
"Advanced". By default, all
parameters are ungrouped. The
group name, "Authorizations" is
reserved for future use.
multilineWrapper no Defines the before and after

text that surrounds the user-
provided parameter value in the
UI text editor that gives context
(for example, that the user is
defining a function) and prevents
users from editing the before
and after parts.
schema yes A JSON schema that describes

the acceptable value for the input
parameter.
parameter multilineWrapper options
The multilineWrapper parameter option provides user-context in the UI when editing the parameter
value. It gives context (for example, that the user is defining a function) and prevents the users from editing
the before and after part of the wrapper. A complete wrapper should use newlines for the best effect.
The before text would trail with a newline, and the after text would lead with a newline. For example, to
achieve an array input so that the user does not have to write the leading "[" or trailing "]":
options:
multilineWrapper:
before: "[\n"
after: "\n]"
When defining a multilineWrapper parameter option, the following table lists the attributes that are
available:
before no The leading text. The text should

trail with a newline.
after no The trailing text. The text should

lead with a newline.
The result will be a UI where the leading before and trailing after will not be editable by the user but
provides necessary context while editing. For example:

[
...
]
output
An output defines a possible way that a method can be resolved. The output is identified by a unique key
below the method's outputs attribute.
An output can be thought of as an event that is triggered when the flow-node resolves at runtime. Typically,
successful resolutions should be listed first, e.g. next, and error resolutions should be listed last, for
example, error.
• Outputs are sorted by name in the UI flow-node configuration panel.

• There is no limit to the number of method outputs.
• Outputs are bound to callback functions and are invoked from actions at runtime.
• The value returned from the callback function is stored in the context at runtime.
• For consistency, you should use Error in your error outputs.
outputs:
next:
name: Next
description: Success
context: $.value
error:
name: Error
description: Something happened
context: $.error
output attributes
The following table lists the attributes available when defining an output:
name no Defaults to the output key. A

friendly name for your output.
This is how it will appear in the
UI. Defaults to the output key.
description no Describes the output value.
context yes A JSON path expression used to

update the runtime context. For
example, $.value.
schema no A JSON schema that describes

the value for the output
parameter.

Actions
An action is a JavaScript function implementation that is defined in the actions.js file. It must be
exported with the same key as the flow-node method key defined in the flow-nodes.yaml file.
function getSomething(req, outputs) {

# ...
}
module.exports = {
getSomething
};
The first argument, req is a runtime context from the flow engine. The flow engine resolves all of the input
parameters that are necessary to invoke the action. If any input parameter fails to resolve, the flow
execution will fail, and the action function will not be called. The request parameters can be accessed via
req.params. The flow-node input parameters can be accessed using the same parameter key as was
defined in the flow-node method (for example, req.param.username). Also, the flow engine will also
provide access to credentials via req.authorizations (see API Builder Credentials for more
information).
• Actions are asynchronous and should resolve using an output callback from outputs when the
operation completes once.
• Action functions should be stateless. Do not use globals or maintain state.
• The action functions should be well written and relatively easy to use from the flow.
function getSomething(req, outputs) {

if (!req.params.username) {
return outputs.error(null, 'invalid username');
}
return outputs.next(null, { user: true });
}
The second argument, outputs is a set of callback functions explained below.
Callback and method outputs
The callback is a function convention for waiting for asynchronous code. You can read more about the
callback convention here. The outputs is a set of callback functions that are keyed to the outputs defined
in the flow-node method. Below is an example callback for the next output:
outputs.next = function(error, arg)
The first argument, error, instructs the flow engine to abort the flow abruptly. It should be used sparingly.
The second argument, arg is the return value for the output callback. At runtime, the value of arg will be
assigned using the context that was defined for the method output (e.g. $.value).
• The callback has an output function for every output defined for the method.
• The callback must only be called once at runtime, and only after all asynchronous tasks are
complete and the action is finished.
Writing unit-tests
The SDK comes with a utility to help test your flow-node, MockRuntime.

const { MockRuntime } = require('@axway/api-builder-sdk');
Your flow-node will be invoked by the API Builder runtime, so it is necessary to mock that runtime to test
your flow-node. You use MockRuntime to do this.
const runtime = new MockRuntime(plugin);
The runtime instance has a validate function that ensures the flow-node adheres to the schema.
it('should define valid flownodes', () => {

expect(runtime.validate()).to.not.throw;
});
Then you can use getFlowNode to obtain a handle to your flow-node and invoke it with various arguments,
checking the response as appropriate.
it('should succeed with valid argument', async () => {

const flowNode = runtime.getFlowNode('myplugin');
const result = await flowNode.getSomething({ username: 'jbloggs' });
expect(result.callCount).to.equal(1);
expect(result.output).to.equal('next');
expect(result.args).to.equal([ null, { user: true }]);
expect(result.context).to.deep.equal({ something: { user: true } });
});
Unit-test API
MockRuntime(obj)
A constructor to return a mock runtime used for testing flow-nodes.
MockRuntime.validate()
Validates the flow-nodes to ensure it adheres to the schema.
MockRuntime.getFlowNode(name)
Obtains a flow-node instance suitable for testing. The actions.js methods are bound to the object
instance as asynchronous functions. For example, if you have an action getSomething:
const flowNode = runtime.getFlowNode('myplugin');

const result = await flowNode.getSomething({ username: 'jbloggs' });
result.callCount
The number of times the output callback was called.
result.args
An array of arguments that were passed into the callback function. The first argument is err, and the
second argument is the response value.
result.output
If a callback output was called, it is the name of the output that was called, e.g. "next". If the default
callback was called, this value is undefined.

result.context
If a callback output was called, it is the name of the output's context that was called. For example, if the
output context is defined as "$.value", then the runtime will write the second callback argument arg
to "value". If the default callback was called or if the output was not defined with a context , then this
value is undefined.
Debugging runtime
To debug the API Builder runtime, you can temporarily add a debugger statement (remember to remove it
after you are done). Depending on how you decided to install the plugin, you may need to run npm install
after adding the debugger statement. It is recommended to use npm-link to make this process easier.
function getSomething(req, callback) {

debugger;
}
Then, you can run npm start with additional arguments that will instruct Node.js to wait for a debugger to
attach. In your API Builder project directory, execute:
npm start -- --inspect-brk
Then attach using a JavaScript debugger. We recommend using Chrome. Browse to:
chrome://inspect/#devices
And then click on the link Open dedicated DevTools for Node. Once attached, you can invoke your flow, and
the debugger should automatically break that your debugger statement.
Debugging unit-tests
To debug unit-tests, the process is much the same as debugging runtime, except that the command to
execute is different. In your plugin directory, execute:
npm test -- --inspect-brk
Programmatic API
There is also an API that can be used to generate flow-nodes programmatically.
Programmatic API
Programmatic API for implementing custom flow-nodes for API Builder flows.
encodeURI example
const { SDK } = require('@axway/api-builder-sdk');
async function getPlugin() {

const sdk = new SDK()
.add('encodeURI', {
name: 'Encode URI',
icon: 'encode.svg',

description: 'URI encoder'

})
.method('encode', {
name: 'Encode URI',
of certain characters with UTF-8 encodings.'
})
.parameter('uri', {
type: 'string',
description: 'The URI to encode.'
})
.output('encoded', {
name: 'Encoded',
description: 'The encoded URI.',
schema: {
type: 'string'
}
})
.action((req, cb) => {
cb.encoded(null, encodeURI(req.params.uri));
});
return sdk.getPlugin();
}
module.exports = getPlugin;
Notice that this encodeURI example is returning a function, getPlugin, that returns a promise. This
allows for the generation of the flow-node to be asynchronous, for example, to allow the loading of content
from a remote source. In this example, it is used for demonstration purposes only, flownodes could have
been returned from getPlugin instead.
Type references
In API Builder, it is possible to reference other JSON schema types. For example, types can be loaded
from ./schemas, registered from Models, or registered from service connectors. Any registered schema
can be referenced whenever a schema is required.
})
.output('next', {
schema: {
}
})
API Reference
api-builder-sdk~SDK
Kind: inner class of api-builder-sdk

• ~SDK
• new SDK(srcModule, [options])
• .add(key, [options]) ⇒ SDK
• .method(key, [options]) ⇒ SDK
• .group(name) ⇒ SDK
• .parameter(name, schema, options) ⇒ SDK
• .output(key, [options]) ⇒ SDK
• .action(handler) ⇒ SDK
• .getPlugin() ⇒ {object}
new SDK(srcModule, [options])
Param Type Default Description
srcModule object a node module
[options] object The options for the

builder.
[options.validate] object true This enables parameter

validation. Disable if you
need to use refs.
SDK.add(key, [options]) ⇒ SDK
Adds a new flow-node and prepares the SDK to accept the following flow-node operations:
• .output(key, [options])
The key parameter is used to uniquely identify the flow-node and represents a distinct instance of a node
for the flow editor. The key will be used as the name unless the name option is provided. The new node will
appear under the "general" category by default, or under the provided category option.
The icon option can be bmp, jpeg, png, gif, tiff, or svg file. After, .method can be used to add method(s),
and .output can be used to define an output. When done, .action can be used to define an action function
and finish the flow-node.
Kind: instance method of SDK Returns: SDK - The current object (this). Access: public
key string A unique key identifier

for the node.
[options] object Options for the node.

[options.name] string A friendly name for the

node as it will appear in
the UI.
[options.icon] string An icon file.
[options.description] string A description for the

node.
[options.category] string "general" A category under which

the node will appear in
the UI (defaults to
"general").
Example
const sdk = new SDK();

sdk.add('encodeURI', { icon: 'encode.svg' });
SDK.method(key, [options]) ⇒ SDK
Adds a new method to the current node flownode and prepares the SDK to accept the following method
operations:

.add(key, [options]) must be called prior to adding a method.
The key uniquely identifies the method for the node and will be used as the name unless the name option is
provided.
Param Type Description
key string A unique key identifier for the

method.
[options] object Options for the method.
[options.name] string A friendly name for the method

[options.description] string A description of the method.
Example

sdk.add('encodeURI', { icon: 'encode.svg' })
.method('encode', { name: 'Encode URI' });

Example (Disable validation)
const sdk = new SDK({ validation: false });

.method('encode', { $ref: '#/definitions/foo' });
SDK.group(name) ⇒ SDK

group as it will appear in the UI.
Example

.group('Advanced')
SDK.parameter(name, schema, options) ⇒ SDK
Adds a new parameter to the current method. Any number of parameters can be added to a method.
.method(key, [options]) must be called prior to adding a parameter.
The name uniquely identifies the parameter, and the schema is a valid JSON Schema definition (both
draft-04 and draft-06 are supported).

schema object A schema used to validate the

parameter.
options object | boolean As an object, specifies additional

options to configure the
parameter. As a boolean,
specifies that the parameter is
required. Parameters are required
by default.
options.required boolean Specifies that the parameter is

required. Parameters are required
by default.

options.multilineWrapper object Describes the before and after

parts that surrounds user-
provided value in the UI.
options.multilineWrapper.before string The read-only string that is

placed before the user-provided
value in the UI.
options.multilineWrapper.after string The read-only string that is

placed after the user-provided
value in the UI.
options.initialType string The type to display by default in

the UI for this parameter. Allowed
values are object, array, string,
selector, null, boolean, and
number.
Example

SDK.output(key, [options]) ⇒ SDK
Adds a new output to the current method. Any number of outputs can be added to a method, but for
usability-sake, you should limit this. The output represents one of the possible callback routes for your
method. For example, if your method tested prime numbers, then one output might be prime, and the other
not-prime.
.method(key, [options]) must be called prior to adding an output.
The key uniquely identifies the output route. The schema is a valid JSON Schema definition (both draft-04
and draft-06 are supported). If schema is not provided, then the output type is effectively any type.
The context is a valid JSON Path and is used as the default by the flow editor. When the output is invoked,
the configured context is where the output value will be written.
key string A unique key for the output.
[options] object output options
[options.name] string A friendly name for the output as

it will appear in the UI.

[options.description] string The output description.
[options.context] string The default context string.
[options.schema] object The expected JSON schema for

the output value.
Example

'string' } });
SDK.action(handler) ⇒ SDK
Assigns an action handler to the current method. The method can only have one action handler. Assigning
an action will terminate the current method definition.
handler handler The action handler function.
Example

'string' } })
sdk.getPlugin() ⇒ SDK
Gets the plugin specification.
Kind: instance method of SDK Returns: {object} - The generated plugin. Access: public
Example

'string' } })


return sdk.getPlugin();
API Builder Web

DeprecationWarning: Beginning with the Lisbon release, API Builder Web is deprecated [D011] and will be
removed in a future major version. If you are currently using Web Routes, consider
switching to another modern web application architecture for your front end that
consumes API Builder Service APIs.
Introduction
This guide covers the basics for creating API Builder Web interfaces. An API Builder Web interface is a
custom endpoint that renders static HTML content to a client application. An API Builder Web interface is
made up of:
• assets (images, CSS, HTML, and JavaScript files) located in the web/public folder
• templates (EJS, Handlebars, Markdown, or React) located in the web/views folder
• API Builder Routes (endpoint definitions) located in the web/routes folder
You can create custom logic in your API Builder Routes, which can internally access your application's
models and APIs.
Route definition
Place all API Builder route definition files in the project's web/routes folder. You can only declare one
endpoint definition per file. An API Builder route definition file is a JavaScript file, which:

2. Calls the module's Router.extend() method, passing in an object defining the API endpoint and
logic.
Set the following keys in the object passed to the Router.extend() method to define the API endpoint.
name true Name of the route.
path true Endpoint/path for the route.
enabled false Specifies whether the route is

enabled. If not, it won’t be
registered, and won’t accept
requests.
sort false An integer that determines the

order routes are registered.
Routes with a higher sort value

are prioritized and registered

earlier. For example, say you
have /route/:id and /route/foo .
If the route with the wildcard has
a higher sort than the static
route, the static route runs.
Therefore, create the first with a
lower sort, and /route/foo
routes properly, as does /api/
bar.
method true The HTTP method (GET, POST,

PUT, DELETE).
description true Description of the route.
action true The function that allows you to

interact with API Builder APIs and
models and send data to your
template engine.
Renderer engines
A renderer engine renders data (or locals in the Express framework) to the view (template file). API
Builder provides a few renderer engines and allows you to add your own custom renderer engines.
Pre-built renderer engines
API Builder Web supports the EJS, Handlebars, Markdown and React renderer engines. Place all template
files with the appropriate extension in the web/templates folder.
To use React, you must install and follow the set-up guide for the @axway/api-builder-react-engine
as it does not come bundled with API Builder.
Renderer Engine File Extension
EJS .ejs
Handlebars .hbs
Markdown .md
React .jsx
To use a template in the API Builder Route's logic, reference its filename without the extension. Because the
template is referenced using the filename, you cannot have the same filename with multiple extensions.
Custom renderer engines
To create a custom renderer engine you need to create a renderer engine and register it with the API
Builder instance's middleware instance.

1. Create an object that implements the createRenderer() method and specifies the extension
property.
2. Pass the object to the Middleware instance's registerRendererEngine() method. You can
retrieve a Middleware instance by using the middleware property of the API Builder instance.
For example, to implement a renderer engine for Jade templates:
var jade = require('jade'),

engine = {};
engine.jade = jade;
engine.createRenderer = function (content, filename, app) {
return function(filename, opts, callback) {
if (!content) {
content = require('fs').readFileSync(filename, 'utf8').toString();
}
callback(null, jade.render(content, opts));
}
};
engine.extension = 'jade';
// server is an APIBuilder instance
server.middleware.registerRendererEngine(engine);
Any view with a jade extension will be routed to the Jade renderer engine.
Handlebars partials and helpers
API Builder exposes some APIs to allow you to register Handlebar partials or helpers.
Helpers
Helpers are functions that you can evaluate in your Handlebar templates. To use a helper, register the helper
with the Handlebar renderer engine, then in the template, call the helper using the name you gave the helper
when registering it.
1. Get a reference to the Handlebar renderer engine using

the APIBuilder.Middleware.getRendererEngine('hbs') method.
2. Call either the Handlebar renderer engine's registerHelper() to register a helper function. Pass
the method the name of the helper and the function to invoke.

hbs = APIBuilder.Middleware.getRendererEngine('hbs');
hbs.registerHelper('doFoo', function(foo) {
// this.name references the name parameter passed to the template
// in the render call, that is, res.render('template', {name: 'Joe'});
if (foo) {
return this.name + ' is great!';
} else {
return this.name + ' is ok.';
}
});
Template example:

<div>doFoo(true)</div>
<div>doFoo(false)</div>
Partials
Partials are subviews that you can embed in a template. To use a partial, you need to register it with the
Handlebar renderer engine, then reference the partial in the template using the {{>
partialName}} syntax, where partialName is the name you gave the partial when you registered it.
1. Get a reference to the Handlebar renderer engine using

the APIBuilder.Middleware.getRendererEngine('hbs') method.
2. Call either the Handlebar renderer engine's registerPartial() to register a partial file. Pass the
method the name of the partial and the template file to use as a partial.

hbs = APIBuilder.Middleware.getRendererEngine('hbs');
hbs.registerPartial('fooView', 'web/views/foo.hbs');
Template example:



<a href="/people/{{id}}">{{name}}</a>


<ul>{{#people}}<li>{{> fooView}}</li>{{/people}}</ul>
API Builder APIs from API Builder Web

You can interact with API Builder APIs from your API Builder Web route. The following is an example.

name: 'car',
path: '/car',
method: 'GET',
req.server.getAPI('api/car', 'GET').execute({}, function(err, results)

{
if (err) {
next(err);
} else {
resp.render('car', results);
}
});
}
});

In the preceding example, the route calls the car API. You can retrieve a reference to an API by specifying
its path or nickname property when specified by the model/API that you are using. For example:
req.server.getAPI('api/car');
getAPI is only compatible with programmatic APIs located in the /apis folder or generated from models. It
cannot be used to retrieve flow-based endpoints.
This code returns a reference to the car API. Once you have the API, you need to call execute:
req.server.getAPI('api/car').execute({}, function(err, results){
});
This first argument to execute is the input required by your API. In this example, none are required
since findAll is being called. The second argument is a callback function. The first argument in the
callback function is an error object. The second is data returned from the API call.
The final part of the example is calling the template with the response data from the API call.
resp.render('car',results);
In this example, car references the name of a handlebars template file (car.hbs) and results contains
the API response with the array of cars.
Following is the handlebars template for this example. It iterates through the cars array.
<html>
<head>
</head>
<body>
{{#each cars}}
<div>{{make}} {{model}} {{year}}</div>
{{/each}}
</body>
</html>
Interacting with models

The preceding example shows how to access APIs from a route. You can also directly access models. The
following modifies the preceding example to use the car model.

name: 'car',
path: '/car',
method: 'GET',
var model = req.server.getModel('car');
model.findAll(function(err, results){
if (err) {
next(err);
} else {

resp.render('car', {cars:results});
}
});
}
});
The first line of the action function retrieves the car model by name:
var model = req.server.getModel('car');
The next line calls the findAll function of the model. It’s important to note that calling APIs is different
than calling models. Calling an API programmatically on the server is nearly identical to calling it remotely -
you supply some input parameters and call execute and it returns the API response. Calling a model
programmatically is slightly different. Since it’s a model, it does not have a REST interface. Instead, it has
the functions that are called underneath the covers when an API is called, so a GET call to an API is the
same as a findAll call on the model. The other difference is in the response data. The model only returns
the data results - hence the results are placed in an object property called car, so the UI template can
render it properly.
As you can see, API Builder Web makes it easy to build responsive desktop and web apps (using your
template engine of choice) that seamlessly integrate with API Builder APIs and models.

API Builder HOW TO
4
This chapter has several sections dedicated to how-to tutorial instructions for API Builder.
• Authorization: Access Gmail using Swagger flow-node

• Authorization: Access Microsoft OneDrive using REST flow-node
• Create a custom flow-node
• Debug a flow
• Deploy an API Builder Standalone application to AMPLIFY Runtime Services
• Dockerize an API Builder Service
• Enable additional CA certificates
• Enable a secure HTTPS listener
• Environmentalization
• Export API Builder Logs into a Data Store
• Import an API Builder API into API Manager
• Set up a project with a connector
Authorization: Access Gmail using Swagger flow-

node
Overview
This example demonstrates how to configure an API Builder application to work with Gmail. It will walk you
through the steps of registering and configuring an application with Google. It will then walk you through
setting up API Builder and authorizing it to access the Google application.
We will then create a flow that uses the Swagger flow-node to invoke the Gmail API and retrieve the number
of the emails received from a provided address.
Creating and configuring Google Application

Before starting on API Builder, you need to register your application on the Google developer console
(https://console.developers.google.com/cloud-resource-manager).
To create a project:
1. Click Create a project.

4 API Builder HOW TO
2. Name your application Gmail Example Project and click Create.
3. Navigate to APIs & Services from the menu.

4. Find and select Gmail API.
5. Click Enable.
6. Click Create Credentials in the information banner that appears.

7. Fill in the following fields and click What credentials do I need?.
8. Fill in the client ID. In this case, we used gmail-auth-client and add http://localhost:8080/
auth/callback as the redirect URI. Then click Create OAuth client ID.

9. Configure the OAuth login screen by providing the product name, in this case, Gmail Connection
Service and click Continue.

10. When the credentials are provided, click Done. We will get the client ID and client secret with the next
step.
11. You should now see the gmail-auth-client in a list of credentials. Click the name.

12. Take note of the Client ID and client secret at the top of the page to which you are redirected. We will
be using these values in API Builder.
Setting up API Builder

Create an example application and install Version 2 of the Swagger plugin:
$ npx @axway/api-builder init gmail-auth

$ cd gmail-auth
$ npm install --no-optional
$ node .
Your service is now running and is accessible on http://localhost:8080/console.
Import the Gmail Swagger flow-node

We will use the Swagger plugin to connect to the Gmail service. To do this, we should locate an up-to-date
Swagger 2.0 definition describing the service. A simplified Gmail Swagger definition is available here:
gmail.json Expand source

{
"swagger": "2.0",
"schemes": [
"https"
],
"host": "www.googleapis.com",
"basePath": "/gmail/v1/users",
"info": {
"contact": {
"name": "Google",
"url": "https://google.com"
},

"description": "Access Gmail mailboxes including sending user email.",

"title": "Gmail",
"version": "v1"
},
"externalDocs": {
"url": "https://developers.google.com/gmail/api/"
},
"Oauth2": {
"authorizationUrl": "https://accounts.google.com/o/oauth2/v2/auth?
access_type=offline&prompt=consent",
"scopes": {
email",
messages and settings"
},
"type": "oauth2"
}
},
"tags": [
{
"name": "users"
}
],
"paths": {
"/{userId}/messages": {
"get": {
"description": "Lists the messages in the user's mailbox.",
"operationId": "gmail.users.messages.list",
"parameters": [
{
"default": false,
"description": "Include messages from SPAM and TRASH in the
results.",
"in": "query",
"name": "includeSpamTrash",
"type": "boolean"
},
{
"default": 100,
"description": "Maximum number of messages to return.",
"in": "query",
"name": "maxResults",
"type": "integer"
},
{
"description": "Page token to retrieve a specific page of results
in the list.",
"in": "query",
"name": "pageToken",

"type": "string"
},
{
"description": "Only return messages matching the specified query.
Supports the same query format as the Gmail search box. For example,
\"from:someuser@example.com rfc822msgid:<somemsgid@example.com> is:unread\".
Parameter cannot be used when accessing the api using the gmail.metadata
scope.",
"in": "query",
"name": "q",
"type": "string"
},
{
"default": "me",
"description": "The user's email address. The special value me can
be used to indicate the authenticated user.",
"in": "path",
"name": "userId",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "Successful response",
"schema": {
"$ref": "#/definitions/ListMessagesResponse"
}
}
},
"security": [
{
"Oauth2": [
"https://mail.google.com/"
]
},
{
"Oauth2": [
"https://www.googleapis.com/auth/gmail.readonly"
]
}
],
"tags": [
"users"
]
}
}
},
"definitions": {
"ListMessagesResponse": {
"properties": {
"messages": {
"description": "List of messages.",
"items": {

"$ref": "#/definitions/Message"
},
"type": "array"
},
"nextPageToken": {
"description": "Token to retrieve the next page of results in the
list.",
"type": "string"
},
"resultSizeEstimate": {
"description": "Estimated total number of results.",
"format": "uint32",
"type": "integer"
}
},
"type": "object"
},
"Message": {
"description": "An email message.",
"properties": {
"historyId": {
"description": "The ID of the last history record that modified this
message.",
"format": "uint64",
"type": "string"
},
"id": {
"description": "The immutable ID of the message.",
"type": "string"
},
"internalDate": {
"description": "The internal message creation timestamp (epoch ms),
which determines ordering in the inbox. For normal SMTP-received email, this
represents the time the message was originally accepted by Google, which is
more reliable than the Date header. However, for API-migrated mail, it can be
configured by client to be based on the Date header.",
"format": "int64",
"type": "string"
},
"labelIds": {
"description": "List of IDs of labels applied to this message.",
"items": {
"type": "string"
},
"type": "array"
},
"payload": {
"$ref": "#/definitions/MessagePart",
"description": "The parsed email structure in the message parts."
},
"raw": {
"description": "The entire email message in an RFC 2822 formatted
and base64url encoded string. Returned in messages.get and drafts.get
responses when the format=RAW parameter is supplied.",

"format": "byte",
"type": "string"
},
"sizeEstimate": {
"description": "Estimated size in bytes of the message.",
"format": "int32",
"type": "integer"
},
"snippet": {
"description": "A short part of the message text.",
"type": "string"
},
"threadId": {
"description": "The ID of the thread the message belongs to. To add
a message or draft to a thread, the following criteria must be met: \n- The
requested threadId must be specified on the Message or Draft.Message you
supply with your request. \n- The References and In-Reply-To headers must be
set in compliance with the RFC 2822 standard. \n- The Subject headers must
match.",
"type": "string"
}
},
"type": "object"
},
"MessagePart": {
"description": "A single MIME message part.",
"properties": {
"body": {
"$ref": "#/definitions/MessagePartBody",
"description": "The message part body for this part, which may be
empty for container MIME message parts."
},
"filename": {
"description": "The filename of the attachment. Only present if this
message part represents an attachment.",
"type": "string"
},
"headers": {
"description": "List of headers on this message part. For the top-
level message part, representing the entire message payload, it will contain
the standard RFC 2822 email headers such as To, From, and Subject.",
"items": {
"$ref": "#/definitions/MessagePartHeader"
},
"type": "array"
},
"mimeType": {
"description": "The MIME type of the message part.",
"type": "string"
},
"partId": {
"description": "The immutable ID of the message part.",
"type": "string"
},

"parts": {
"description": "The child MIME message parts of this part. This only
applies to container MIME message parts, for example multipart/*. For non-
container MIME message part types, such as text/plain, this field is empty.
For more information, see RFC 1521.",
"items": {
"type": "object"
},
"type": "array"
}
},
"type": "object"
},
"MessagePartBody": {
"description": "The body of a single MIME message part.",
"properties": {
"attachmentId": {
"description": "When present, contains the ID of an external
attachment that can be retrieved in a separate messages.attachments.get
request. When not present, the entire content of the message part body is
contained in the data field.",
"type": "string"
},
"data": {
"description": "The body data of a MIME message part as a base64url
encoded string. May be empty for MIME container types that have no message
body or when the body data is sent as a separate attachment. An attachment ID
is present if the body data is contained in a separate attachment.",
"format": "byte",
"type": "string"
},
"size": {
"description": "Number of bytes for the message part data (encoding
notwithstanding).",
"format": "int32",
"type": "integer"
}
},
"type": "object"
},
"MessagePartHeader": {
"properties": {
"name": {
"description": "The name of the header before the : separator. For
example, To.",
"type": "string"
},
"value": {
"description": "The value of the header after the : separator. For
example, someuser@example.com.",
"type": "string"
}
},
"type": "object"

}
}
}
We will also provide an icon with the Swagger definition to make it more identifiable. Any svg, png, gif, bmp,
jpg, or tiff format file can be used. In this example, we use an image from iconfinder.com.
1. Save the Swagger definition above to a file named gmail.json.

2. Place the file gmail.json inside the /swagger directory of your project.
3. Navigate to https://www.iconfinder.com/icons/132837/gmail_icon.
4. Click Download PNG.
5. Save the downloaded file as gmail.png in the /swagger directory of your project. It is important that
the file name matches the Swagger file name.
6. Restart your service.

7. Navigate to the Credentials tab and notice that a Gmail credential has been automatically created. For
the credential to be ready, we need to provide the client id and client secret.
Configure Gmail Credential

For more information on OAuth 2.0 credentials, see OAuth 2.0 credentials.
For Gmail, to get the credential ready, we need to configure the generated credential with our tokens. This
credential is inside a configuration file that was generated by the Swagger plugin when the service was last
started.

1. Navigate to the Configuration tab.
2. Select gmail.default.js. This is the configuration file that was generated.

3. We then need to get the Gmail Client ID and Client Secret from the Google developer console and add
them to the configuration file as client_id and client_secret.
4. Click Save and then Proceed on the subsequent modal.

5. After the service restarts, open the Credentials tab.
If everything went well, your Gmail Oauth2 credential would have changed from an error state to
requiring authorization.
6. To authorize the credential, click Authorize.

7. You will be prompted to choose a Google account or log in. Here you will log in with the account that
you wish to count the emails from. The account must also have the Gmail service enabled.

8. Once you've logged in, you will be prompted to authorize access.

9. Click Allow to authorize the service. The credential is now ready to use.
By default, the access tokens issued by Google will expire in 1 hour. API Builder will keep the access token
valid by refreshing it before its expiration. However, the access token and refresh token are stored in
memory only, and if you restart API Builder, you will need to authorize the credential again.
Create an API to count your emails

Before creating the flow, you need to import the API that will expose your flow. Stoplight.io is a great
resource for designing APIs and was used to create a very simple API used for this example. This is a very
simple API with a single endpoint.
Create the countEmail.json Swagger document
1. Copy the following code into a text editor such as Notepad++:
countEmail.json Expand source

{
"swagger": "2.0",
"info": {
"title": "Gmail Count Service API",
"version": "1.0"
},
"host": "localhost:8080",
"basePath": "/api",
"paths": {
"/gmail/count": {
"get": {
"responses": {

"200": {
"description": "Count",
"schema": {
"type": "number",
"minimum": 0
}
},
"500": {
"description": "Error Occurred",
"schema": {
"type": "object"
}
}
},
"parameters": [
{
"in": "query",
"name": "from",
"type": "string",
"required": true,
"format": "email"
}
],
"operationId": "countGmailEmails",
"produces": [
"application/json"
],
"description": "Count the emails received from a user"
}
}
}
}
2. Name the file countEmail.json and save the file. You will import this file as an API Endpoint.

Import the API Endpoint
1. Open the API Doc & Test tab.
2. Click +API.

3. Import the countEmail.json Swagger document. Refer to Create the countEmail.json Swagger
document.
4. Click Save. This will create the API endpoint in a disabled state, as there is no flow attached to it.
Create the flow for the API Endpoint
On the disabled endpoint, there is a Create Flow icon. Clicking Create Flow will start the Flow Editor where
you can create the logic for your API.
We will go through the steps to create the flow, but for reference, the completed flow that we're building will
look like this:

1. Drag a Mustache node from the tool panel. We will use this node to create a Gmail query string that
will contain filter the emails from a certain address.
a. Click on the Format string title and rename it to Format Query for clarity.
b. On the Parameters tab, set data to be the selector $.params.from.
c. Click Edit Mustache and set the value to the following string:
from:{{data}}

d. On the Outputs tab, change the Next output to $.query.

2. Connect the Start node to the Format query node. Drag in a Gmail flow-node from the tool panel and
make sure that the gmail.users.messages.list method is selected. We will use this to connect
to Gmail and request the emails.
a. Click on the gmail.users.messages.list title and rename it to Get Emails for clarity.
b. Connect the Next output of the Format Query node to the new Get Emails node.
c. On the Parameters tab, change the type of the parameter to Credential and then select the
credential we configured earlier - Gmail Oauth2.
d. Set userId to the string value me indicates that we want to access emails for the authenticated
user.
e. Set q to the selector $.query.
On the Outputs tab, you will see that the 200 response is stored as $.response. We will extract
the response data from that later.


3. Drag an HTTP flow-node from the tool panel; this only has a single Set HTTP Response method. We
will use this node to configure the response that is returned to the caller.
a. Connect the 200 output of the Get Emails node to the new Set HTTP Response node.
b. Click on the Set HTTP Response title and rename it to Success for clarity.
c. On the Parameters tab, set the status to be of type Number with the value 200. Set the body to
$.response.data.resultSizeEstimate.
4. Drag in another HTTP flow-node from the tool panel. We will use this node to configure the error
response that is returned to the caller in the event of an error. For this demonstration, we will have a
single error status - 500.
a. Connect each of the Error outputs from the Format Query and Get Emails nodes to this Set
HTTP Response node.
b. Click on the Set HTTP Response title and rename it to Server Error for clarity.
c. On the Parameters tab, set the status to be of type Number with the value 500. Set
the body to $.error.message. In production, this is not recommended but helps to debug any
error which may occur during development.
5. Drag a Set Context flow-node from the tool panel. This will be used to create a new Error that we will
return if the Default output of Get Emails is triggered.
a. Connect the Default output of Get Emails to the Set Context node.
b. Click on the Set Context title and rename it to Set Error.
c. On the Parameters tab, set the value to be an object representing the error that we want to return
from the API. In this example, we use the following Object value:
{ "message": "Unexpected gmail response" }

d. On the Outputs tab, set the Next output to $.error
e. Connect the Next output of Set Error to the Server Error node.
f. Click Apply and Close.
Test your Endpoint

1. Open the Credentials tab and check that your credential is authorized. If it isn't, perform the credential
authorization.

3. Click on your Gmail Count Service API and expand the GET method.

4. Input an email address for as the value for from and click Execute to test your API. You should get
back a number indicating the number of emails from that address.
This was a simple integration between API Builder and Gmail to access the list of contents. You can use a
similar approach to work with any API; all you need to provide is the Swagger document describing the API
and API Builder can integrate with it seamlessly.
Authorization: Access Microsoft OneDrive using

REST flow-node
Overview
This example demonstrates how to configure API Builder to work with OneDrive. It will walk you through the
steps of registering and configuring an Application with Microsoft. It will then walk you through setting up
API Builder and authorizing it to access the Microsoft application.
We will then create a flow that uses the REST flow-node to invoke the OneDrive API and retrieve a list of
contents.
Creating and configuring Microsoft Application

Before starting on API Builder, you need to register your application on the Microsoft application portal
(https://apps.dev.microsoft.com/).

Add an app
1. Click Add an app.

2. Name your application OneDrive Example and click Create.

3. Click Save.
Configure Application Secrets
The Application Id displayed in the Properties section will be the value of the client_id in the API
Builder credential. You also need to create a client_secret.
Click Generate New Password. The value displayed will be your client_secret; this is the only time it's
visible, so make a note of the value and don't lose it. If you lose it, you can repeat this step to generate a
new client secret.

Configure Platform
1. You need to add OAuth support to your application and add the API Builder redirect URI. Under
Platforms, click Add Platform.
2. Select Web.
This will add a Web panel to the Platforms list.

3. Uncheck Allow Implicit Flow (API Builder will not be doing an implicit grant).
4. Set the Redirect URLs to http://localhost:8080/auth/callback.
Configure Permissions
In this example, you will be reading the user's files.

Click Add next to Delegated Permissions. From the list select:
• Files.Read
• offline_access
Save your Application
If you haven't already done it, save your application.
Setting up API Builder

Create an example application:
$ npx @axway/api-builder init onedrive-example

$ cd onedrive-example
$ npm install --no-optional
$ node .
Your service is now running and is accessible on http://localhost:8080/console.
Create OneDrive Credential

For more information on OAuth 2.0 credentials, see OAuth 2.0 credentials.
To create the credential, you need the following information.
Key Value Description
flow accessCode The OAuth 2.0 access code grant

flow.

authentication_url https:// The authorization URL will

login.microsoftonline.com/ depend on the service to which
common/oauth2/v2.0/authorize you are connecting. Consult the
vendor documentation for the
values, for Microsoft's identity
service, see: https://
developer.microsoft.com/en-us/
graph/docs/concepts/
auth_overview
token_url https:// The token URL, like the

login.microsoftonline.com/ authorization URL, will depend on
common/oauth2/v2.0/token the service you are connecting to.
Consult the vendor
documentation for the values, for
Microsoft's identity service, see:
https://
developer.microsoft.com/en-us/
graph/docs/concepts/
auth_overview
client_id 47d6acc1-d388-4449- This is the Application Id for the

b16d-7d43d8dfe107 application you registered.
client_secret bFJGT4298@uesjeeBJD0~}; This is the secret you generated

when registering the application.
scope https://graph.microsoft.com/ These are the scopes that our

files.read offline_access example application will require
and which we have enabled
earlier when creating the
Application.
For information on how scopes
are formatted in Microsoft Graph
see https://
docs.microsoft.com/en-us/
azure/active-directory/
develop/v2-permissions-and-
consent
access_token null This value must be present, and

null for this example.
refresh_token null This value must be present, and

null for this example.
1. On the Configuration tab, open the default.js file. Scroll to the credential section of the file.
Create a new OAuth 2.0 credential:
default.js
authorization: {
callback: '/auth/callback',

credentials: {
'My OneDrive': {
type: 'oauth2',
flow: 'accessCode',
authentication_url: 'https://login.microsoftonline.com/common/
oauth2/v2.0/authorize',
token_url: 'https://login.microsoftonline.com/common/oauth2/
v2.0/token',
client_id: '47d6acc1-d388-4449-b16d-7d43d8dfe107',
client_secret: 'bFJGT4298@uesjeeBJD0~};',
scope: 'https://graph.microsoft.com/files.read offline_access',
access_token: null,
refresh_token: null
}
}
}
2. Click Save and then open the Credentials tab.
If everything went well, you should now have a credential named My OneDrive.
3. The credential has not been authorized. To authorize the credential, click Authorize.

4. Once you've logged in, you will be prompted to authorize access.

5. Click Accept. The credential is now ready to use.
By default, the access tokens issued by Microsoft will expire in 1 hour. API Builder will keep the access
token valid by refreshing it before its expiration; this is why it needs the offline_access scope. However,
the access token and refresh token are stored in memory only, and if you restart API Builder, you will need to
authorize the credential again.
Create a flow to list the OneDrive contents
Before creating the flow, you need to import the API that will expose your flow. Stoplight.io is a great
resource for designing APIs and was used to create a very simple API used for this example. This is a very
simple API with a single endpoint.
Create the onedrive.json Swagger document
1. Copy the following code into a text editor such as Notepad++:
onedrive.json Expand source

{
"swagger": "2.0",
"info": {
"title": "One Drive Auth Demo API",
"version": "1.0",
"description": "A sample API for the API Builder OneFrive
Authorization Demo.",
"license": {
"name": "MIT"
},
"contact": {
"name": "Axway",

"email": "sales@axway.com",
"url": "http://www.axway.com"
}
},
"host": "localhost:8080",
"paths": {
"/contents": {
"get": {
"responses": {
"200": {
"description": "",
"schema": {
"type": "object",
"properties": {}
}
},
"400": {
"description": ""
},
"500": {
"description": ""
}
},
"summary": "This endpoint will list the contents of the OneDrive
account.",
"operationId": "GetContents",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"description": "Get the contents of the OneDrive account.",
"tags": [
"api-builder",
"onedrive",
"authorization"
]
}
}
},
"basePath": "/api",
"schemes": [
"http"
],
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
{
"name": "api-builder onedrive authorization"

},
{
"name": "api-builder"
},
{
"name": "onedrive"
},
{
"name": "authorization"
}
]
}
2. Name the file onedrive.json and save the file. You will import this file as an API Endpoint.
Import the API Endpoint
2. Click +API.

3. Import the onedrive.json Swagger document. Refer to Create the onedrive.json Swagger
document.
4. Click Save. This will create the API endpoint in a disabled state, as there is no flow attached to it.
Create the flow for the API Endpoint
On the disabled endpoint, there is a Create Flow icon. Clicking Create Flow will start the Flow Editor where
you can create the logic for your API.
We will go through the steps to create the flow, but for reference, the completed flow that we're building will
look like this:

1. Drag an Authorization flow-node from the tool panel. The Authorization flow-node only has a single
Get Credential method. This method allows us to retrieve the managed credential token from API
Builder.
a. On the Parameters tab, set the name to be My OneDrive. This is the name you gave your
OneDrive credential when creating it in the configuration.
b. On the Outputs tab, you can see that the credential token is stored in $.credential. We will
use this later when invoking OneDrive.


2. Drag a Compose flow-node from the tool panel and select the Format object method. We will use
this node to create the request headers object that will contain the authorization token.
a. Connect the next output of the Get Credential node to the new Format object node.
b. Click on the Format object title and rename it to Format Headers for clarity.
c. On the Parameters tab, set the data to be $.credential, and set the template to:
{
"Authorization": "Bearer {{=it}}"
}
d. On the Outputs tab, change the Next output to $.headers.


3. Drag in a REST flow-node from the tool panel and select the GET method. This is the node that will
make the request.
a. Connect the Next output of the Format Headers node to the new GET node.
b. On the Parameters tab, set the URL to https://graph.microsoft.com/v1.0/me/drive/root/children.
Microsoft has a useful Graph Explorer tool that you can use to explorer their API.
c. Also, set the Headers to $.headers, which is the object you created in the previous step.
On the Outputs tab, you will see that the 2XX response is stored as $.response. We will extract
the response data from that later.


4. Drag in another Compose flow-node from the tool panel and select the Format object method. We
will use this node to create a response body.
a. Connect the 2XX output of the GET node to the new Format object node.
b. Click on the Format object title and rename it to Format Response for clarity.
c. On the Parameters tab, set the data to be $.response.body and set the template to:
[
{{~it.value :entry:index}}
{{? index }}, {{?}}
{
"name": {{=JSON.stringify(entry.name)}},
"webUrl": {{=JSON.stringify(entry.webUrl)}}
}
{{~}}
]
For more information on the DoT template language, see Use doT template language.

d. On the Outputs tab, change the Next output to $.contents.

5. Drag an HTTP flow-node from the tool panel; this only has a single Set HTTP Response method. We
will use this node to configure the response that is returned to the caller.
a. Connect the Next output of the Format Response node to the new Set HTTP Response node.
b. Click on the Set HTTP Response title and rename it to Success for clarity.
$.contents.
6. Drag in another HTTP flow-node from the tool panel. We will use this node to configure the error
response that is returned to the caller in the event of an error. For this demonstration, we will have a
single error status - 400.
a. Connect all the error outputs and all the unconnected outputs from the GET node to the Set
HTTP Response node.
b. Click on the Set HTTP Response title and rename it to Bad Request for clarity.
$.error.message.
7. Click Apply and Close.
Test your Endpoint
1. Open the Credentials tab and check that your credential is authorized. If it isn't, perform the credential
authorization.

3. Click on your One Drive Auth Demo API and expand the GET method.
4. Click Execute to test your API. You should get back a list of the name and webUrls of the contents of
your OneDrive account.

This was a simple integration between API Builder and OneDrive to access the list of contents, but this
same approach applies to the entire Microsoft Graph API, and so the integration possibilities are endless.
Create a custom flow-node

This document describes how to create a custom flow-node.
Introduction
As an example of how to write a flow-node, we will examine creating and customizing a sample encodeURI
flow-node that URI encodes a string. Creating and customizing the sample flow-node includes the following
steps:
1. Create the project

2. Customize the flow-node definition
3. Customize the flow-node method implementation
Prerequisites
• Install API Builder per the getting started instructions in the API Builder Getting Started Guide.
• Install the Axway Flow SDK per the install instructions in the Axway Flow SDK.
Create the sample encodeURI flow-node

This tutorial will demonstrate how to create a custom flow-node for use in the API Builder Flow editor UI. For
this example, we will create a flow-node that will encode a URI given a string as an input using the
encodeURI function.
Step 1: Create the project
Create and build the sample encodeURI flow-node.
Create a new flow-node plugin

axway-flow -n encodeuri -d "URI encoder."
cd api-builder-plugin-fn-encodeuri
npm run build
Step 2: Customize the flow-node definition
Customize the encodeURI flow-node definition in the index.js file.
Expand source
const sdk = require('axway-flow-sdk');
const action = require('./action');
function getFlowNodes() {
const flownodes = sdk.init(module);
flownodes
.add('encodeuri', {
name: 'Encode URI',
icon: 'icon.svg',
description: 'URI encoder.',

category: 'utils'
})
.method('encode', {
name: 'Encode URI',
of certain characters with UTF-8
encodings.'
})
.parameter('uri', {
description: 'The URI to encode.',
type: 'string'
})
.output('next', {
name: 'Next',
description: 'The URI was encoded successfully.',
schema: {
type: 'string'
}
})
.action(action);
return Promise.resolve(flownodes);
}
exports = module.exports = getFlowNodes;
To explain what occurs in the index.js file, we will break the file down piece by piece.
1. index.js is exporting a function that returns a promise that will resolve with the flow-node
specifications. This approach allows for the asynchronous creation of the flow-node specifications,
which can be used, for example, to load resources from the network or perform asynchronous parsing.
2. In the sample flow-node plugin, the actual specification is defined in getFlowNodes().
3. Provide the flow-node name, icon, description, and category:
.add('encodeuri', {
name: 'Encode URI',
icon: 'icon.svg',
description: 'URI encoder.',
category: 'utils'
})
The name is the text that is displayed in the Flow Editor. The default icon is a placeholder (a star) that
should be replaced with a graphic that represents the action of the flow-node. The icon is displayed at
28 pixels by 28 pixels. The category is the section in the Flow Editor tool panel where the flow-node
is contained.
4. Add a method to the flow-node and describe its parameters:
.method('encode', {
name: 'Encode URI',
description: 'Encodes a URI by replacing each instance of certain
characters with UTF-8 encodings.'

})
.parameter('uri', {
type: 'string'
})
A method called encode, that is displayed in the Flow Editor as Encode URI, was added. The encode
method has a single parameter. If there were more than one parameter, we would repeat
the .parameter(name, schema)block. The second value in the parameter method is a JSON
Schema that describes the parameter type.
5. Describe the possible outputs from the method:
.output('next', {
name: 'Next',
description: 'The URI was encoded successfully.',
schema: {
type: 'string'
}
})
The outputs section defines the possible outcomes of the flow-node. In this simple case, there is just
one output; however, flow-nodes can have multiple outputs with different return types. For example,
this flow-node could have added an error output to indicate that encoding failed.
6. Define the implementation:
.action(action);

The action() expects a function that will be passed the request details parameter and a callback
object parameter.
Step 3: Customize the flow-node method implementation
To simplify the management of the code, the starter project puts the implementation of the methods in the
action.js file. There is not a requirement to follow this pattern; you can structure your project how best
suits your needs.
exports = module.exports = function (req, cb) {

const uri = req.params.uri;
if (!uri) {
return cb('invalid argument');
}
cb.next(null, encodeURI(uri));
};
This is a simple scenario, but it highlights the main features. The parameters for the flow-node method are
accessed under the req.params parameter. In this example, the parameter for the encode method is
defined as uri:
.parameter('uri', {
type: 'string'
})
The logic checks that the parameter is set. If the uri parameter is not set, it fires a generic error callback.
return cb('invalid argument');
These errors are not handled and will abort the flow execution. In general, avoid doing this for any expected
error scenarios. If there are known error situations, it is better to define an output for those scenarios and
allow the flow designer the flexibility to specify what to do when an error occurs.
If the uri parameter is set, the fallback for the next output is fired. The name of this callback will match the
name of the output defined in the method. For example, if you defined an output encoderError, then there
would be a callback cb.encoderError(). The encoded string is passed to the callback as the methods
output value.

Debug a flow
This document describes how to add parameters and execute flows using the new Flow Editor debug
feature.
Introduction
Beginning with the Osaka release of API Builder Standalone, the ability for Flows to be provided with
parameters and executed without having to leave the Flow Editor has been added. For additional
information on managing flows using the Flow Editor, refer to Manage Flows.
Prerequisites
• Install the Osaka release of API Builder Standalone per the getting started instructions in the API
Builder Getting Started Guide.
• Navigate to the Flow Editor using the View Flows instructions in Manage Flows.
Debug a flow
To debug a flow and enter parameters using Flow Editor debug feature:
1. Click the Bug icon. Clicking the Bug icon opens the Parameters tool. Flow Parameters are JSON
objects used when executing the flow. You can access values by using a selector from Flow-node
parameters. For example, a flow with a parameter that uses the $.params.username selector will

need to provide an object which defines the username. For example: { "username": "test" }
2. Enter a valid parameter in the Parameters field.

3. Click Execute Flow. Clicking Execute Flow will execute the flow. Once the flow execution is completed,
a Flow response will be returned.
4. To execute the flow again, click Retry.

5. To close the Parameters tool, click the Bug icon.
Troubleshoot Parameters field entries

To troubleshoot Parameters field entries:
1. Verify that you have entered valid parameters in the Parameters field. Invalid parameter field entries
will be highlighted. Hovering over the highlight will display troubleshooting tips for correcting

parameter entry. Correct the parameter entry per the troubleshooting tips.
2. Verify that the parameter entry is complete. If parameter entry is incomplete, errors will occur while
debugging the flow. Provide a complete parameter entry and click Retry

Deploy an API Builder Standalone application to

AMPLIFY Runtime Services
Introduction
This topic describes how to create, Dockerize, and publish an API Builder Standalone application to
the AMPLIFY Runtime Services cloud. Prerequisites, instructions, and references are provided to help you
successfully deploy and publish your application to the AMPLIFY Runtime Services cloud and to test your
published application.
Prerequisites
The following sections describe the prerequisites.
AMPLIFY Platform account
You need to have an account on https://platform.axway.com.
Docker
The installation of Docker is via a dedicated installer for your specific operating system. For additional
Docker installation information, refer to the Docker documentation.
API Builder CLI
The API Builder CLI is a node module published in the npm public repository. To install, execute the
following command:
Install API Builder CLI

$ npm install -g @axway/api-builder
For additional API Builder CLI installation information, refer to the API Builder Getting Started Guide.
AMPLIFY Cloud Services (ACS) CLI
The AMPLIFY Cloud Services CLI (ACS) is a node module published in the npm public repository. To install,
execute the following command:
Install ACS
$ npm install -g acs
For additional AMPLIFY Cloud Services CLI information, refer to the AMPLIFY Runtime Services Command-
Line Interface Reference.
Create your application

API Builder CLI usage can be found here. This the setup found in the API Builder Getting Started Guide. This
will create a "myproject" sub-directory.
Create an API Builder project

$ api-builder init myproject

Create your Platform application

Log in to the AMPLIFY Platform using your https://platform.axway.com username and password. Create a
project in the cloud with the same name as your "myproject" sub-directory. Then, configure your project to
use PORT 8080. This is because the container is built with PORT 8080 by default.
Create an API Builder project

$ acs login
$ acs new myproject --force
$ acs config --set PORT=8080 myproject
ImportantWarning: You may already have an existing project, "myproject". If you do, and you know that it is
not being used and you wish to delete it, or if you want to delete this example project on
ARS, you can execute: acs remove myproject.
Build a Docker image

To build a Docker image of your project, execute the following commands.
Build Docker image

$ cd ./myproject
$ docker build --tag demo-image ./
Publish image to Platform

To publish the Docker image of your project to the Platform, execute the following command.
Publish image
$ acs publish myproject --delete_oldest --force --image demo-image --
app_version 0.1
ImportantWarning: It can take up to 10 minutes for your project to be deployed and your service to be
accessible. You should Check publish status before trying to access your service in the
cloud.
Once the image is written, note the URL, as you will use it to test your API, for example:
URL
App will be available at https://<guid>.cloudapp-enterprise.appcelerator.com
Check publish status

Even though your image was sent to ARS, it can take up to 10 minutes to start (for example, Status:
Deploying). You should check the Status of your project before trying to access your service that is
running in the cloud. The service will not be available until status shows Status: Active.
$ acs list myproject
You can also check the log of your project to see if it started properly.
$ acs logcat myproject

Try your application

To try your application in the cloud, you will require your API key, which can be found in "myproject/conf/
default.js". On successful publication of your project, you also received a URL with a GUID prefix to access
your application from the Internet. Replace the <key> and <guid> with the API key and GUID values in the
following command.
$ curl -u "<key>:" https://<guid>.cloudapp-enterprise.appcelerator.com/api/

greet?username=Bob
Dockerize an API Builder Service

This document describes how to run an API Builder service or application in a Docker container.
Introduction
If you have previously created API Builder services, you already know that generating an API Builder service
with the help of the API Builder CLI tool is relatively easy. However, you may want to run your service from
within a Docker container so it can be weaved and used as part of a more complex solution.
This document provides a step-by-step tutorial on how to run an API Builder service within a Docker
container. These steps include:
1. Scaffold and run the API Builder application.

2. Prepare to run your service within a Docker container.
3. Create a Docker image for your service.
4. Run the Docker container and access your service.
These steps and their required prerequisites are described in the following sections.
Prerequisites
You need to have the following installed:
1. Docker - The installation of Docker is via a dedicated installer for your specific operating system. For
additional Docker installation information, refer to the Docker documentation.
2. API Builder CLI - The CLI is a flow-node module published in the npm public repository. It is a one-line
command as follows:
npm install -g @axway/api-builder
For additional API Builder CLI installation information, refer to the API Builder Getting Started Guide.
Dockerize an API Builder Service

To Dockerize an API Builder Service, complete the following steps.
Step 1: Scaffold and Run API Builder Service
If you already have a generated service, you can proceed to Step 2.
To scaffold and run your API Builder service, execute the following commands:

api-builder init <SERVICE_NAME>

cd <SERVICE_NAME>
npm start
Once your project is running, point your browser to http://localhost:8080/console to access the
API Builder user interface (UI) console.
For additional information on the API Builder UI, refer to the API Builder Getting Started Guide.
Excellent! Now, you have tested that your service is running directly on your machine.
Now, stop the service by using Ctrl + C in your terminal where the service is running and go to the next step.
The following variable placeholder is used in this section:
Variable Placeholder Description
<SERVICE_NAME> This is your chosen service name that the API

Builder CLI is using. For example: myservice
It will create a folder with the chosen name and will
place all the generated files in that folder.
Step 2: Prepare to run your service within Docker
In Step 1, we showed the traditional way of running your service locally. Now, let's see how to run your
service within a container.
When running your service in a container, it is often desirable to have the configuration (or parts of it) set at
runtime rather than relying on static values.
To achieve this, you can update the configuration files to read from the environment.
In Node.js, this is done with reading variables from process.env; for example,
process.env.<VARIABLE_NAME>.
Configuration Files Types
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
The following table lists the configuration files, their location, and their example content. Note that this
tutorial does not require a connector to be installed. The connector configuration is shown to inform you
that you will have to provide an additional set of environment variables when dockerizing an API Builder
service with connectors.

default.js apiKey:
process.env.APIKEY

port:
T) || 8080
};
Connector Configuration Example with MySQL. Expand source

The file will be named module.exports = {
<SERVICE_FOLDER> /conf/ connectors: {
mysql.default.js mysql: {
connector:
plugin-dc-mysql',
connectionLimit:
10,
host:
|| 'localhost',
port: 3306,
# This could be
set to mysql since this
is already available
database by default
database: 'mysql',
user:
password:
RD,
// Create models
that can be used in
your API.
: true,
// Whether or not
on the methods in
generated models.
modelAutogen:
false
}
}

};
Excellent! Now, you have defined which variables can be provided at runtime while starting your Docker
container.
Now, let's see how to prepare your Docker image and how to run Docker container out of it.
Step 3: Create a Docker image for your service - meet the Docker file
API Builder applications come with a with an example Docker file. When a service is generated with the API
Builder CLI, the generated service has a Docker file in its root directory.
This file is just one possible Docker file that can be used for the Docker image creation. You can tailor the
Docker file to your specific needs.
The sample Docker file content is:
Expand source
# See the README.md for usage and configuration info
# This line defines which node.js Docker image to leverage

# Available versions are described at https://hub.docker.com/_/node/
FROM node:8-alpine
# Sets the default working directory to /app which is where we've copied the
service files to.
WORKDIR /app
# TODO: for security purposes, you should update this Dockerfile to specify
your own target user/group
# -S stands for '--system'
# -G stands for group
# -R changes the ownership rights of a file recursively
RUN addgroup -S axway-group && adduser -S axway-user -G axway-group && \
chown -R axway-user:axway-group /app
# Set non-root user

USER axway-user
# Denotes to copy all files in the service to 'app' folder in the container
COPY . /app
# Install service dependencies relevant for production builds skipping all

development dependencies.
RUN npm install --production --no-optional
# Starts the service

CMD ["node", "."]
If you want to specify your user and password, you can use ENV (Environment Variables) in the APP
Dockerfile. For example:

# Set specific user & password using Env Vars

ENV NONROOT_USER="<user>"
RUN adduser $NONROOT_USER && \

echo $NONROOT_USER":<password>" | chpasswd
USER $NONROOT_USER
The Docker image can be created with the following command:
docker build -t <IMAGE_NAME> ./
Now, you can run as many containers as you want out of the created Docker image. To check for the
presence of the newly created image, run the following command:
docker image ls
The Docker image with the <IMAGE_NAME> should be visible in the listed images.
The Docker images can be pushed to a Docker registry, such as Docker Hub, Google Container Registry, or a
private registry; however, for this tutorial, the locally built images will be used.
See the Docker Push documentation for information on how to push your image or repository to a Docker
registry.
The following variable placeholder is used in this section:
<IMAGE_NAME> This is your chosen docker image name. For

example: myservice
Docker uses this name to create the Docker image
for the service.
After the creation of the image, the docker image ls
command should show an image with the created
image name in the list of available images on your
machine.
Step 4: Run the Docker Container and Access the Service
Things to observe when running your service within a Docker container:
1. Set Environment Variables: Make sure that you provide values for all the environment variables that
have no default values, as well as on those where you have to change the default values. Make sure
you provide values not only for service configuration; but also for all the connectors you have installed
in your service.
2. Production Deployment: Because the image is built in production mode, the service is no longer
editable. The API Builder console will not be available.
3. Run Multiple Services: Having containerized your service, it is now possible and generally desirable, to
run multiple instances of your service. This allows you to address load balancing, scalability, and the
resilience of your service.
Next, we will show two approaches to run the Docker container.

Use the first approach if you don't want to map ports on your host machine and the second approach if you
want to access the service as if it is running on your localhost.
Approach 1: Running Docker Container - Plain
Using the image created in Step 3, you can now run a Docker container.
Running Docker container will execute the CMD specified in the Docker file, and your service will be started.
docker run --name <CONTAINER_NAME> <IMAGE_NAME>
How to provide environment variables for Docker container?
If you want to run the service within a Docker container and provide runtime values for those properties that
are configured to be read from the environment (see Step 2), use the following command:
# Run the container setting the port where the service will run within the
container to 8081
docker run --name <CONTAINER_NAME> -e PORT=8081 <IMAGE_NAME>
Other useful commands:
# If you want to see that your container is running

# You should see <CONTAINER_NAME> in the list of started containers
docker container ls
# Once ran the running container could be stopped with

docker container stop <CONTAINER_NAME>
# ... and started again with

docker container start <CONTAINER_NAME>
How to access the service?
First, you need to check the IP Address that Docker is using to run your container:
docker inspect <CONTAINER_NAME> | grep '"IPAddress"' | head -n 1
Now, check the value of your apikey property in <SERVICE_FOLDER>/conf/default.js file.
Using the apikey, you can execute the following command:
curl -X GET -u <API_KEY>: "http://<IP_ADDRESS>:<PORT>/api/greet?

username=APIBuilder"
The following variable placeholders are used in this section:
<IMAGE_NAME> This is the name of the docker image specified by

you in the previous step.
<CONTAINER_NAME> This is your chosen docker container name. For

example: mycontainer

Docker will use this name to run a container based

on the Docker image specified with
<IMAGE_NAME>.
<API_KEY> Must be replaced with the value of the apiKey

property specified in <SERVICE_FOLDER>/conf/
default.js file.
<IP_ADDRESS> Should be replaced with the value returned by the

command: docker inspect
<CONTAINER_NAME> | grep '"IPAddress"'
| head -n 1
<PORT> 8080 if not overridden.
Approach 2: Running Docker Container - Detached Mode with Port Mapping
Using the image, you can run and access a Docker container with the following commands:
# Run the container exposing the port 8080 to your host so the app is
accessible on that port
docker run --name <CONTAINER_NAME> -p 8080:8080 -d <IMAGE_NAME>
# Now access with

curl -X GET -u <API_KEY>: "http://localhost:8080/api/greet?username=APIBuilder"
Alternatively, to override the port, you can execute the following commands:
# Note that if you provide another port with -e option you must map that
provided port value to the desired port number of the host machine
# The example below runs the service within container on 8081 and maps that
port to 8082 of the host machine
docker run --name <CONTAINER_NAME> -e PORT=8081 -p 8082:8081 -d <IMAGE_NAME>
# Now access with

curl -X GET -u <API_KEY>: "http://localhost:8082/api/greet?username=APIBuilder"
The Docker options are:
Docker Options Description
-d Runs the container in the background and prints the

container ID.
-p Allows you to map ports on your host machine to

ports inside the container. For example:
<host_port>:<container_port>
The following variable placeholders are used in this section:

<IMAGE_NAME> This is the name of the docker image name

specified by you in the previous step.
<CONTAINER_NAME> This is your chosen docker container name. For

example: mycontainer
Docker will use this name to run a container based
on the Docker image specified with
<IMAGE_NAME>.
<API_KEY> Must be replaced with the value of the apiKey

property specified in <SERVICE_FOLDER>/conf/
default.js file
Step 5: Accessing your service documentation
By default, API Builder generates Swagger 2.0 documentation for your service, which is available from
http://localhost:8080/apidoc/swagger.json. If you choose to expose your container through a
proxy, handle SSL termination outside API Builder, or have path mapping on your service, you will want to
modify your API service documentation to reflect this.
In the project configuration, the documented Swagger host, basePath, and schemes can be customized to
values that would result in your API service documentation matching the production environment. For
example, if your production deployment is an SSL terminating proxy, you need to have your service
documentation include its host and port. These can be configured using environment variables in the same
way as prior examples have shown.
conf/default.js
module.exports = {
apidoc: {
overrides: {
host: process.env.APIDOC_HOST,
basePath: '/apis',
schemes: [ 'https' ],
}
}
};
Enable additional CA certificates

This document describes how to enable additional certificate authority (CA) certificates.
Introduction
In closed environments, self-signed or privately signed certificates are commonly used, and rejected by
Node.js since their root CAs are not known.
As of Node.js 7.3.0 (and LTS versions 6.10.0 and 4.8.0), it is possible to add well-known extra certificates to
Node.js with a NODE_EXTRA_CA_CERTS environment variable. It can be useful in the cloud environment or

other deployment environments to add trusted certificates as a matter of policy (as opposed to explicit
coding), or on personal machines, for example, adding CAs for proxy servers.
Prerequisites
You need to have the following:
• Node.js 7.3.0 or above
Documentation and resources

Useful resources on how to use the product:
• nodejs.org
• CA certificate structure
Set the additional CA certificates

To set the additional CA certificates, use the following environmental parameter:
NODE_EXTRA_CA_CERTS=file
When set, well known "root" CAs (like VeriSign) will be extended with the extra certificates in a file. The file
should consist of one or more trusted certificates in PEM format. A "process.emitWarning()" message will
be emitted (once) if the file is missing or malformed, but any errors are otherwise ignored.
Note that neither the well known nor extra certificates are used when the ca options property is explicitly
specified for a TLS or HTTPS client or server. For more informaton, check the link!
Step 1: Create and download your certificate
The file should consist of one or more trusted certificates in PEM format.
File structure example:
extra-ca-certs.pem
-----BEGIN CERTIFICATE-----
{your certificate}
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
{your certificate}
-----END CERTIFICATE-----
Step 2: Add NODE_EXTRA_CA_CERTS to your env variables
In the terminal:
export NODE_EXTRA_CA_CERTS=./extra-ca-certs.pem
In the package.json file:
"start": "NODE_EXTRA_CA_CERTS=./extra-ca-certs.pem node ."
In the Docker container:

docker run --name <CONTAINER_NAME> -e NODE_EXTRA_CA_CERTS=./extra-ca-certs.pem

-p 8081:8081 -d <IMAGE_NAME>
Enable a secure HTTPS listener

This document describes how to enable secure HTTPS listener for an API Builder service.
Introduction
The generation of API Builder services is a simple process with the help of the API Builder CLI tool.
Some users may want to run their APP using the Secure Sockets Layer (SSL), so this document describes
how to make the necessary configuration changes. Additionally, this document provides the technical
requirements and an example of how to scaffold and run an API Builder service and configure SSL.
Prerequisites
Before setting up a service and configuring SSL, refer to:
• API Builder Getting Started Guide - Provides detailed instructions for installing API Builder and creating
an API Builder service.
• API Builder Project - Provides detailed information about API Builder projects and services.
• Install the API Builder Command Line Interface (CLI) globally using npm. It is a flow-node module
published in the npm public repository. Once API Builder CLI is installed, you can use it to create a new
service, install the service's dependencies, and start the API Builder service.
npm install -g @axway/api-builder
• OpenSSL - Provides detailed information about OpenSSL.

• API Builder Documentation

• Axway Appcelerator Youtube Channel
• Appcelerator Blog
Configure SSL
This document provides a step-by-step tutorial on how to run an API Builder service and configure SSL.
These steps include:
1. Scaffold and run the API Builder service.

2. Create an SSL certificate.
3. Configure SSL in the API Builder service.
These steps and their required prerequisites are described in the following sections.
Step 1: Scaffold and Run API Builder Service
If you already have a generated service, you can proceed to Step 2.

To scaffold and run your API Builder service, execute the following commands:
api-builder init <YOUR_APP_NAME>

cd <YOUR_APP_NAME>
npm start
Once your service is running, point your browser to http://localhost:8080/console, for access to
the API Builder user interface (UI) console.
For additional information on the API Builder UI, refer to the API Builder Getting Started Guide.
Now, stop the service by using Ctrl + C in your terminal where the service is running and go to the next step.
Step 2: Create an SSL certificate
Create one new folder on the root level of your directory.
cd <api-builder-service>
mkdir <new-folder>
Navigate to the newly created folder and create an SSL certificate via OpenSSL. Please execute the
following command:
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -
subj "/C=US/O=Axway/CN=API Builder"
Warning: -subj "/C=US/O=Axway/CN=API Builder" is the default DN.
Due to the generation process, you will need to set PEM passphrase; for example, this is a password that
must be supplied by anyone wanting to use the keys.
Once your certificate is created, you will find two new files in your <new-folder>; for example, the
key.pem file that will store the private key and the cert.pem file, which is the certificate.
In case you specified the PEM passphrase when generating the certificate, there is a password that must be
supplied by anyone wanting to use it.
Warning: Additional information is available at Creating an HTTPs server with Node.js and NodeJS and
SSL.
Step 3: Configure SSL in the API Builder service
Navigate to the ./conf/default.js file from the root of your project. Your SSL configuration goes here.
The options are the same as what is used by the Node.js https.createServer() method. You will find the
initial SSL configuration. For example:
// ssl: {
// port: 8443,
// key: fs.readFileSync(path.join('.', 'ssl','key.pem'), 'utf8'),
// cert: fs.readFileSync(path.join('.', 'ssl','cert.pem'), 'utf8'),
// passphrase: 'secret'
// }

Enable SSL by uncommenting the configuration. Once the configuration is uncommented, add a key and
certificate, provide the paths to the files, and provide a password for the private key (configured as an OS
environment variable). The following is the sample configuration:
ssl: {
port: 8443,
key: fs.readFileSync(path.join('.', 'ssl','key.pem'), 'utf8'),
cert: fs.readFileSync(path.join('.', 'ssl','cert.pem'), 'utf8'),
passphrase: process.env.API_BUILDER_SSL_PASSWORD
}
The code fragment above is using 'fs' and 'path' modules which must be required on top of your
configuration file as follows:
const fs = require('fs');
const path = require('path');
Then navigate to the root directory of <your-project> and run the service using the following command:
API_BUILDER_SSL_PASSWORD=<your-passphrase-key-password> npm start
Disable HTTP
In cases when HTTPS listener is activated the user might want to disable the HTTP traffic.
This can be done using the disabled property of http configuration flag:
http: {
port: parseInt(process.env.PORT) || 8080,
disabled: true|false // false by default
}
Warning: Additional information is available at API Builder Configuration for both ssl and http configuration
options.
Environmentalization
Introduction
The best practice for building a Twelve-Factor App is to separate or decouple the configuration from the
application. Environmentalization is the simplest method to decouple the configuration from the
application.
While the API Builder Project Configuration allows developers to configure their applications with
configuration files, these values are static and hard-coded into the application. However, and quite often,
applications need different configurations for different environmental contexts in which they are run, or they
require sensitive configuration, such as credentials, that must never go into unsecured application
configuration files. For example, it is often necessary to use one set of credentials locally, but use some
other set of credentials when running in a different environment. To ensure that the application can run in
any environment, it is necessary to decouple configuration from the application.

Decoupling the configuration is the process whereby configuration is replaced with values that are sourced
elsewhere (for example, from the host environment), enabling the application (or container) to be run
anywhere.
In this document, we will take the simplest approach, which is to replace configuration values with host
environment variables. This is sometimes referred to as "environmentalizing". For example:
./conf/default.js
module.exports = {
password: process.env.PASSWORD
};
When API Builder starts up, it will look for the OS environment variable PASSWORD, if it's not set, the value
will be undefined, but if it is set, the value is always a string.
Setting the value of PASSWORD is going to be specific to the OS you are using (or host).
For example, on Linux PASSWORD can be set from the command line:
$ setenv PASSWORD=secret
With Docker containers, PASSWORD can be provided with docker run.
$ docker run -e PASSWORD=secret --tag myapp:latest
With AMPLIFY Runtime Services, the PASSWORD can be provided with the appc command.
$ acs config --set PASSWORD=secret myapp
Note that this is only one way to decouple your application from its configuration. There are other (more
complex) ways, for example, such as obtaining these values from an external configuration server. This
document gives you the basis upon which you can tailor your solution.
API Builder provides an easy way to specify environment variables in your development environment.
However, it does not address the management of configuration parameters other environments, for
example, production, nor does it address how those values are protected. How you address those
environments is entirely up to you. For example, you may add production environment variables values to
your CI system, or you may choose to create a script to set them. Whatever you choose, it should be secure
and align with your CI/CD process and should meet security best-practices.
Local environment file

Decoupling the configuration from the application makes the application very flexible. However, it also
means that it is a pain when you want to run it. You will likely run the application locally quite often, so for
this reason, a feature was added in the API Builder Barcelona release to load from a local ./conf/.env file.
If this file exists, it is loaded by API Builder on startup, and its values are augmented with the host OS
environment variables. Values from this file are only applied if the host OS does not already have the value
set.
./conf/.env (default)
PORT=8080
LOG_LEVEL=debug
The config/.env file will often contain sensitive information, so it is protected so that it can only be read
by the user that created it (not supported on Windows), and will not be bundled as part of Docker, and it will

never be committed to source control. If you upgrade an existing application to the Barcelona release, you
will need to create the file manually and ensure it is protected.
Optional
Using ./config/.env for development is entirely optional, but it will make development much easier.
./config/.env usually contains sensitive information like usernames and passwords.
By default, this file is never added to npm, git, or docker.
Make sure this stays the same, and file is not committed into public repositories. It should stay local.
Configuration value types

As discussed, configuration parameters usually have specific type requirements, such as string, number, or
boolean. Environment values that are sourced from the OS are always strings. Therefore, when using them
in configuration, it is important to convert them to the expected type. Also, the conversion is not straight
forward. For example, parseInt will return NaN if passed an undefined value. When converting values, you
have the full spectrum of JavaScript at your disposal.
Default values
Sometimes you want to default to a value when it is not specified as an environment variable. You can use
the || operator to provide a default when the environment value is falsey.
./conf/default.js
module.exports = {
default: process.env.DEFAULT || 'hiya'
};
Converting integers
Integers should get converted with parseInt. Be careful with unexpected values as parseInt can return NaN.
For example, parseInt('foo'), and parseInt(undefined) both return NaN. If NUMBER is not set in
the environment, its value is undefined.
./conf/default.js
module.exports = {
number: parseInt(process.env.NUMBER || 0, 10)
};
Converting floats or decimals
Decimals should get converted with parseFloat. Be careful with unexpected values as parseFloat can
return NaN. For example parseFloat('foo'), and parseFloat(undefined) both return NaN. If
DECIMAL is not set in the environment, its value is undefined.
./conf/default.js
module.exports = {
decimal: parseInt(process.env.DECIMAL || '3.14', 10)
};

Converting booleans
Converting Boolean values requires fineness as there is no direct conversion in JavaScript. It largely
depends on how user-friendly you want to be, for example, arguments could be made for accepting "1",
"true", "TRUE", or "0", "false", or "FALSE". You could write a parseBoolean function and use that, or be careful
when you define the values in the target host environment.
./conf/default.js
module.exports = {
boolean: process.env.BOOLEAN === 'true'
};
Formatting strings
Sometimes a configuration value is a composite of different environment values. For example, when you
want a database URI and a separate database name. These can be formatted using the javascript template
literal operator, ``.
./conf/default.js
module.exports = {
connect: `${process.env.DATABASE_URL}/${process.env.DATABASE_NAME ||
'default'}`
};
Complex example
Below is a complex example using environment variables with multiple files. Let's assume that we have a
simple API Builder service with MongoDB connector installed, then the configuration related files in
the service/conf directory will be:
$ ls -1a conf/
.env
mongo.default.js
default.js
greetflow.default.js
The main application is decoupled to the source APIKEY, PORT, and LOG_LEVEL from the environment in
conf/default.js:
./conf/default.js
module.exports = {
apikey: process.env.APIKEY,
baseurl: 'http://localhost',
logLevel: process.env.LOG_LEVEL,
...
}
The MongoDB connector is configured to obtain the value MONGODB_CONECTION from the environment:
./conf/mongo.default.js
module.exports = {
connectors: {
mongo: {
connector: '@axway/api-builder-plugin-dc-mongo',

url: process.env.MONGODB_CONNECTION,
generateModelsFromSchema: false,
modelAutogen: false
}
}
};
You also set values in your conf/.env file to make development easier:
./conf/.env
# Service
APIKEY=123
PORT=8080
LOG_LEVEL=debug
# Mongo DB Connector
MONGODB_CONNECTION='mongodb://localhost/apibuilder'
In the above example:
• The environment variables APIKEY, PORT, LOG_LEVEL, and MONGODB_CONNECTION will be available
to the runtime;
• The values of those environment variables will match the values specified in the .env file (unless they
are set in the host environment previously);
• The configuration parameters that point to these environment variables - apikey, port, logLevel,
and url (from mongo config) - will use the values from conf/.env.
Export API Builder Logs into a Data Store

This document describes how to export Logs from an API Builder application or service into a data store.
Introduction
The generation of API Builder applications is a simple process with the help of the API Builder CLI tool.
Some users may want to run the application and use a Business Intelligence (BI) tool so that they can
export logs into a third-party party data store (DS).
This document provides the technical requirements and an example of how to scaffold and run an API
Builder application or service and export its logs into Splunk.
Prerequisites
Tools to be installed and prerequisites:
1. Install the API Builder Command Line Interface (CLI) globally using npm. It is a flow-node module
published in the npm public repository. Once API Builder CLI is installed, you can use it to create a new
project, install the project's dependencies, and start the API Builder project. Refer to the API Builder
Getting Started Guide for detailed information.

2. Docker - The installation of Docker depends on the specific operating system. For additional
information on how to install Docker and its supported operating systems, refer to the Docker
installation documentation.
3. Dockerize Application - Refer to Dockerize API Builder Application for detailed information on to
dockerize an application or service. Read the documentation carefully and prepare to run your service
within Docker. When running your service in a container, it is often desirable to have the configuration
set at runtime and to read parameter values from the environment rather than relying on static values.
4. Research BI tools - Research BI tools and 3rd party data stores. For example, Splunk, Elastic, and so
forth.
Warning: For additional resource information, refer to the Docker getting started tutorial, Dockerizing a
Node.js web app, and docker-node.

• API Builder Documentation

• Axway Appcelerator Youtube Channel
• Appcelerator Blog
• Docker Documentation
• Configure logging drivers in Docker
General description of the integration process

When you create a service using API Builder, you may want to integrate the service with an existing
monitoring, audit, or BI system.
While there are several different ways to integrate your service with an existing BI system, this document
describes integration with Splunk. The same integration principles that apply to Splunk are also applicable
to other aggregators such as Elastic, Awslogs, Gcplogs, and so forth.
Logs export using Docker

The BI tool is a platform for operational intelligence. The software lets you collect, analyze, and act upon the
untapped value of big data that your technology infrastructure, security systems, and business applications
generate. It gives you insights to drive operational performance and business results. For information on the
API Builder logging strategy, refer to Logging. For information on debugging and setting the logging for your
application or service, refer to Debugging.
Configure logging drivers
Docker includes multiple logging mechanisms to help you capture logging information from running
containers and services. These mechanisms are called logging drivers.
Each Docker daemon has a default logging driver, which each container uses unless you configure it to use
a different logging driver.
In addition to using the logging drivers included with Docker, you can also implement and use logging driver
plugins. Logging driver plugins are available in Docker 17.05 and higher.

If the logging driver has configurable options, you can set them in the daemon.json file as a JSON array
with the log-opts key. The following example sets two configurable options in the json-file logging
driver:
{
"log-driver": "json-file",
"log-opts": {
"labels": "production_status",
"env": "os,customer"
}
}
To find the current default logging driver for the Docker daemon, run the docker info command and search
for Logging Driver. You can use the following command on Linux, macOS, or in PowerShell on Windows:
$ docker info | grep 'Logging Driver'

Logging Driver: json-file
Warning: Read the following documentation and make the configuration changes: Configure logging drivers
and Docker JSON File logging driver.
Splunk logging driver
Splunk makes it simple to collect, analyze and act upon the untapped value of the big data generated by
your technology infrastructure, security systems, and business applications, and gives you the insights to
drive operational performance and business results.
The splunk logging driver sends container logs to the HTTP Event Collector in Splunk Enterprise and
Splunk Cloud.
You can configure Docker logging to use the splunk driver by default or on a per-container basis.
The common way to use the splunk driver as the default logging driver is to set the log-driver and
log-opts keys to appropriate values in the daemon.json configuration file and restart Docker. For
example:
{
"log-driver": "splunk",
"log-opts": {
"splunk-token": "",
"splunk-url": "",
...
}
}
The daemon.json file is located in the /etc/docker/ directory on Linux hosts or in the C:
\ProgramData\docker\config\daemon.json directory on Windows Servers. For more information
about configuring Docker using the daemon.json file, see daemon.json.
To configure the splunk driver for a specific container, use the --log-driver and log-opt command-
line flags with the docker run command:
docker run --log-driver=splunk --log-opt splunk-token=VALUE --log-opt splunk-

url=VALUE ...

Warning: For helpful information about the Splunk logging driver, refer to Splunk logging driver.
Run Splunk via Docker
1. Run the following command to pull the latest version of the Splunk Enterprise image:
docker pull splunk/splunk
2. Run the Docker image:
docker run -d -e "SPLUNK_START_ARGS=--accept-license" -e

"SPLUNK_USER=root" -p "8000:8000" splunk/splunk
3. Access the Splunk instance with a browser by using the Docker machine IP address and Splunk Web
port. For example: http://localhost:8000
Warning: For additional resources information, refer to Docker/Splunk Enterprise.
Splunk HTTP Event Collector
The Splunk HTTP Event Collector (HEC) enables you to send data to Splunk Enterprise and Splunk Cloud.
HEC lets you send data, application logs, and metrics over HTTP (or HTTPS) directly to Splunk Enterprise or
Splunk Cloud from your application. HEC operates with tokens, which means you do not need to embed
Splunk Enterprise or Splunk Cloud credentials in your application or supporting files.
Warning: Additional information is available at: How HTTP Event Collector works, Overview of Splunk
logging for JavaScript and Bunyan stream for HTTP Event Collector and Splunk-javascript-
logging.
Setup Splunk Server
Now, we will set up the Splunk server with basic definitions in a local environment using the Docker Splunk
logging drive and the HTTP event collector.
1. Pull the Splunk image from the Docker hub as follow:
docker pull splunk/splunk
2. Check the Splunk image as follows:
docker images | grep splunk
3. Start the Splunk server and bind it to the service port using the following command:
docker run -d -e "SPLUNK_START_ARGS=--accept-license" -e

"SPLUNK_USER=root" -p "8000:8000" -p "8088:8088" splunk/splunk
4. Navigate to https://localhost:8000/ in your browser and verify that the Splunk server is up.
5. Go to Settings > Data inputs > HTTP Event Collector > Add new.
6. Enter a name and select the Next button.

7. Verify that you that have successfully generated a Token.
8. Copy and save the Token.
9. Navigate to Settings/Data inputs/ HTTP Event Collector and to see your Docker logs.
10. Click to Global settings button and Enable button and to find HTTP Port Number.

11. Click on the Docker logs edit button and leave the default settings.
12. If you navigate to the App: Search & Reporting page, the following UI will be displayed.
13. Once you have the Splunk container running and have set up everything in the Splunk Web, you are
ready to run the application container via Splunk. You need to set the application container to the
same port that you used for binding in the previous command. For the splunk-url, you need to use
your IP address. The Service-Image should be the image name that you already built in your API
Builder service.
Please use the below command:
docker run -d -p 8080:8080 --log-driver=splunk --log-opt splunk-url=http://

<IP>:8088 --log-opt splunk-token=<TOKEN> --log-opt splunk-
insecureskipverify=true <Service-Image>
14. Verify that you are receiving your application logs in the Splunk Web UI. If everything works correctly,
you will automatically receive all your application logs in the Splunk Web UI.

The Logs imported into Splunk will be displayed as in the following examples.
Example one:
Example two:

Import an API Builder API into API Manager

This document describes how to import an API Builder API into API Manager.
Introduction
API Manager provides a web-based interface that enables an API owner (either in a technical business role
or IT operational role) to easily register back-end REST APIs, apply policies, and to virtualize them on the API
Gateway. In this document, we will explore how API Builder services can be managed by API Manager.
Prerequisites
This document assumes that you are familiar with API Manager and have it deployed and running in your
infrastructure. For more information on API Manager, refer to the API Manager Guide or sign up for an API
Management Trial.
This document also assumes that you have API Builder installed and that you have created and deployed a
service. For this document, we will use the vanilla starter application, which will be referred to as the API
Builder Greet service. The API Builder Greet service is created when you execute the following command:
npx @axway/api-builder init <name>
For configuration purposes:
• API Manager is deployed on apimgmt.gateway.192.168.99.100.nip.io

• API Builder Greet service is deployed on greet.apibuilder.192.168.99.100.nip.io
To configuration the API Manager outbound authentication, you need to know the API key of the API Builder
Greet service.
Registering with API Manager

If you know API Manager and how to virtualize backend services, integrating API Builder will be a familiar
process. The steps are:
1. Login
2. Import the backend API
3. Virtualize the frontend API
Login
Open API Manager and log in. In this case, the URL is https://apimgmt.rdpp-4522.192.168.99.100.nip.io/
home.

Import the backend API
1. The first step is to import the Swagger service definition for the backend Greet service into API
Manager. In the API section, click Backend API.
2. Click New API.

3. Select Import Swagger API.
4. API Manager requires the URL of the Swagger definition of the API Builder Greet service. Since the
service is deployed and running, we will select a Swagger definition URL. API Builder exposes the
Swagger definition for the service under greet.apibuilder.192.168.99.100.nip.io.
Warning: In this example, the Greet service is being hosted in a Kubernetes cluster with Ingress rules.
This is why in the image, the URL is using HTTPS and not specifying the port.
5. Name the backend API Greet and associate it with an organization in your API Manager setup. Once
imported, Greet will be listed in the Backend API section.
Virtualize and configure the backend API
To allow API Manager to manage the backend API, you need to virtualize it. Virtualizing the API creates a
frontend API proxy for your service.

1. Navigate to the Frontend API tab.
2. Click New API.

3. Select New API from backend API.
4. Select Greet 1.0.0 in the dialog (this is the name of the backend service that we imported earlier).
5. For demonstration purposes, we will leave the frontend API unsecured (Pass-through). On the
Inbound tab, select Pass Through from the Inbound Security drop-down menu.
Warning: This is purely for demonstration purposes; API Manager has many authentication
mechanisms built-in and is extensible using policies. See Virtualize REST APIs in API
Manager for more information.

By default, API Builder services are secured using an API key. The default mechanism for passing this
key is to use HTTP Basic authentication, where the key is the username, and the password is blank. If
you are using a different authentication mechanism for your API Builder service, then this step might
differ.
6. On the Outbound tab, for Outbound authentication profile, select HTTP Basic.
7. Add the Greet service API Key as the username.
Warning: The API key is set in the conf/default.js file in your API Builder application and is also
displayed on the console when the service starts.

8. Save the frontend API. The Greet API should now be listed as a Frontend API.
API Catalog
The Greet API will now be listed in the API Catalog.
If you view the catalog entry for Greet, you can view the documentation and try out the APIs.

Testing the APIs
At this stage, you should be able to test your API using tools like cURL or Postman. However, for
convenience, API Manager has built-in support for testing your APIs. This can be accessed via the catalog
or in the Frontend API. Before using it, some extra configuration is required; the API Manager UI runs on port
8075, whereas the APIs managed by API Manager are hosted on port 8065. Browser security will treat this
as a cross-origin request, so to test the APIs from the browser UI, we need to enable CORS.
1. In the Frontend API section, open the Greet API and open its CORS section.
2. Add a new CORS configuration.
Warning: For convenience, we are granting access to all domains. Using * in production should only be
done after assessing the security implications.
To test the API, click the Try It button. In this case, we're testing GET /api/greet. This is a simple API that
takes a username and responds with a greeting string.

Further Integration
Now that your services are being managed by API Manager, you can leverage the entire arsenal of available
features that it provides. These include:
• Built-in support for common authentication mechanisms such as OAuth, HTTP Basic, API Key, Two-
way SSL, and more.
• Integration with third-party Identity Management (IM) infrastructures for authentication and
authorization.
• Add governance to traffic using policies; for example, to ensure sensitive information isn't being
leaked in the response. See Configure API Manager settings in Policy Studio for further information.
• Apply quotas on APIs. See Administer APIs in API Manager for more information.
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
Before setting up a project with a connector, refer to:
• API Builder Getting Started Guide - 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

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.
Warning: Refer to API Builder Connectors for detailed information.
Available connectors
The following connectors are available for download directly from NPM:
• @axway/api-builder-plugin-dc-mongo
• @axway/api-builder-plugin-dc-mysql
• @axway/api-builder-plugin-dc-mssql
• @axway/api-builder-plugin-dc-oracle
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
Warning: 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
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.


default.js apiKey:
process.env.APIKEY
port:
T) || 8080
};
Connector Configuration Example with MySQL. Expand source

The file will be named module.exports = {
<SERVICE_FOLDER> /conf/ connectors: {
mysql: {
mysql.default.js
connector:
plugin-dc-mysql',
connectionLimit:
10,
host:
|| 'localhost',
port: 3306,
# This could
be set to mysql since
this is already
available database
by default
database: 'mysql',
user:
password:
RD,
// Create models
that can be used in
your API.
: true,
// Whether or not

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.

fields: {
},
connector: 'mysql'
});

fields: {


},
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.

API Builder Release Notes
5
API Builder Standalone - Huddersfield
Summary
This release includes:
• Upgrade
• Features
• Fixes
• Release Notes
• Updated Modules
• Known Issues
Upgrade
To update an existing API Builder Standalone application, execute the following command from within the
application directory:
npm update
Features
• #4899: Add plugin init command to CLI and new plugin SDK
• #6139: Support loading data connectors that fail to connect
• #6152: Add support for installing Components
Fixes
• #6142: Restart signal (SIGUSR2) causes exception

• #6174: Add examples link to SDK
Release Notes
• #4899: Added a new command plugin init to the @axway/api-builder CLI to enable plugin projects
to be created via the CLI.
• #4899: Created a new SDK @axway/api-builder-sdk for writing plugins and improved the experience.
• #6139: Previously, if a connector failed to connect on startup, e.g. with missing credentials, then API
Builder would exit. Now, API Builder will allow connectors to fail to connect on startup, provided that
they are not used in a flow, or generate model API, or are used in a composite model.
• #6142: Previously, API Builder was failing to restart on SIGUSR2 signal with the error "server failed to
start". Now, it restarts successfully when that signal is received.

5 API Builder Release Notes
• #6152: Introduced a new feature that allows easy installation of Axway supported API Builder
components via the Connectors page in the UI.
• #6174: Updated the SDK documentation and examples.
Updated modules
• @axway/amplify-api-builder-cli@1.2.6
• @axway/api-builder-runtime@4.21.4
• @axway/api-builder-admin@1.14.0
• @axway/api-builder@4.14.1
Known Issues
• #3825: Filtering the API Builder Console administrator access using IPv6 addresses may cause
ENOTFOUND errors.
• #3867: When attempting to create and save a flow for an imported Swagger endpoint that contains a
path or paths defined by references, the save will fail.
• #3979: Attempting to delete an endpoint in the UI that was created as a result of dereferencing a
JSON $ref will yield a 404 error. API Builder will fail to locate the method since it only exists when the
whole Swagger document is dereferenced. An example of a Swagger document using $ref:
{
"swagger": "2.0",
"paths" {
"x-path": {
"get": {}
},
"/find": {
"$ref": "#/paths/x-path"
},
"/search": {
}
}
}
• #4528: Initializing a new project with api-builder init 1234 where 1234 is any number will
throw an ERR_INVALID_ARG_TYPE error rather than an "invalid npm package name" error.
• #4735: Invoking Upsert will fail for all data connectors when creating a composite model from an
existing model and renaming one of the fields.
• #4749: A query on a distinct API created from the Mongo plugin (@axway/api-builder-
plugin-dc-mongo) does not honor the value of the order parameter.
• #4750: The Upsert or FindAndModify methods are not present in the APIs generated from Mongo or
MySQL connector based models.

• #4751: The FindAndModify method from APIs created using the Mongo plugin (@axway/api-
builder-plugin-dc-mongo) responds with a 404 error rather than creating a new entry when the
upsert parameter is true.
• #4752: The format of a distinct query response depends on the type of connector.
• #4759: Calling Update or FindAndModify on a model that uses the composite connector and contains
the required fields may fail and cause the server to terminate.
• #4795: The MongoDB plugin @axway/api-builder-plugin-dc-mongo does not support primary

keys that are not object identifiers correctly. The MongoDB specification allows for primary keys of
other types. As a result, trying to use the plugin will result in errors:
{
"message": "Invalid Value for Find By ID: 'YOUR_STRING_PK_NAME'",
"success": false,
"request-id": "c118f187-2090-4a68-b939-37367ac55b80"
}
• #4813: If the endpoint Swagger file in the /endpoints folder contains special characters in its name,
for example [test].json, the endpoint is not rendered correctly in the UI.
• #4856: Passing in an invalid column name as a parameter to APIs generated from data connectors
may result in an exception being thrown rather than the callback being executed with an error. A
similar error may occur when using model flow-nodes, resulting in an error which cannot be handled
by the flow.
• #4859: When endpoints are generated from a model, the endpoint descriptions do not use the correct
plurals defined by the model.
• #4865: The Swagger flow-node plugin strips characters from valid object definition names which can
result in schema ID collisions.
• #4865: The Swagger flow-node plugin does not handle valid object definition names with ~ or / in their
name which can result in an invalid schema references in Swagger flow-nodes.
• #4951: When endpoint or flow files with URL encoded characters in the filename are present in a
project, unexpected errors may occur. For example, the wrong flow or endpoint could be modified.
Using files with encoded characters in their names is not recommended.
• #4961: Having the % symbol in various file names can cause problems in the API Builder Console and
with direct linking. It is therefore advisable to avoid using % in API, Endpoint, Flow, Model, and
Configuration file names. This is a result of an issue in react-router/history. For additional information,
refer to https://github.com/ReactTraining/history/issues/505.
• #4966: API Builder will generate invalid Swagger for programmatic APIs in ./apis that bind to a path
other than the apiPrefix defined in the configuration. These APIs must be bound to the same root
path as defined by the apiPrefix.
• #5538: A model with a single-quote "'foo" is a valid model name, but not a valid endpoint name, so the
single-quote will be stripped when generating endpoints. If another model "foo" exists and has
generated endpoints, then generating endpoints for "'foo" with single-quote, will overwrite existing
endpoints for "foo". The following characters are stripped from model names: "?", ":", "'", and
".".

• #6150: Stoplight always encodes default parameter values as strings, even though the type may not
be a string (e.g. "number"). The Swagger validation will fail with an error, e.g. "Not a valid number". To
work around the problem, you can manually change the parameter default from a string (e.g. "42") to
a number (e.g. 42) by editing the Swagger directly, but that is not always an option. Alternatively, you
can change the parameter type to a "string", and add a validation "pattern", e.g. "[0-9]+".
Recent Releases
• API Builder Standalone - 17 January 2020
• API Builder Standalone - 20 December 2019
• API Builder Standalone - 6 December 2019
• API Builder Standalone - 22 November 2019
• API Builder Standalone - 8 November 2019
• API Builder Standalone - 11 October 2019
• API Builder Standalone - 27 September 2019
• API Builder Standalone - 30 August 2019
API Builder Standalone - 17 January 2020

API Builder Standalone - Huddersfield
Summary
• Upgrade
• Features
• Fixes
• Release Notes
• Updated Modules
• Known Issues
Upgrade
npm update
Features
• #4899: Add plugin init command to CLI and new plugin SDK
• #6139: Support loading data connectors that fail to connect
• #6152: Add support for installing Components

Fixes
• #6142: Restart signal (SIGUSR2) causes exception

• #6174: Add examples link to SDK
Release Notes
• #4899: Added a new command plugin init to the @axway/api-builder CLI to enable plugin projects
to be created via the CLI.
• #4899: Created a new SDK @axway/api-builder-sdk for writing plugins and improved the experience.
• #6139: Previously, if a connector failed to connect on startup, e.g. with missing credentials, then API
Builder would exit. Now, API Builder will allow connectors to fail to connect on startup, provided that
they are not used in a flow, or generate model API, or are used in a composite model.
• #6142: Previously, API Builder was failing to restart on SIGUSR2 signal with the error "server failed to
start". Now, it restarts successfully when that signal is received.
• #6152: Introduced a new feature that allows easy installation of Axway supported API Builder
components via the Connectors page in the UI.
• #6174: Updated the SDK documentation and examples.
Updated modules
Known Issues
ENOTFOUND errors.
{
"swagger": "2.0",
"paths" {
"x-path": {
"get": {}
},
"/find": {
},
"/search": {

}
}

{
"success": false,
}
by the flow.

".".
API Builder Standalone - 20 December 2019

API Builder Standalone - Ghent
Summary
• Upgrade
• Features
• Fixes
• Release Notes
• Updated Modules
• Plugins
• Known Issues
Upgrade
npm update
Features
• #6138: Introduce list of available and installed Connectors

Fixes
• #6143: Make it easier to configure SSL

• #6144: Saving flow a second time causes an error that a flow already exists
• #6146: Composite model using SQL join having primary key does not return expected results
• #6153: Fix link to JavaScript flow-node
Release Notes
• #6138: Introduced a new feature that allows the easy discoverability of all existing API Builder
connectors and plugins. These API Builder components are now accessible within the scaffolded
application on the Connector's page.
• #6143: Configuration file now includes clear explanation and example of how to configure SSL.
• #6144: Previously, new flows would fail to save using Apply a second time. Now, they save as
expected.
• #6146: Previously, a composite model (A) that joins one model with another (B) where the name of the
field being joined on B was the same name as the primary key for A, would fail to join as expected and
return unpredictable results. Now, composite models will join as expected.
Updated modules
Updated plugins
• @axway/api-builder-plugin-fn-javascript@1.2.2
Known Issues
ENOTFOUND errors.
{
"swagger": "2.0",
"paths" {
"x-path": {
"get": {}
},
"/find": {

},
"/search": {
}
}
}

{
"success": false,
}
by the flow.

".".

API Builder Standalone - Florence
Summary
• Upgrade
• Features
• Fixes
• Release Notes
• Deprecations
• Updated Modules
• Plugins
• Known Issues
Upgrade
npm update

Features
• #6099: Support option to disable all HTTP traffic when HTTPS is enabled
Fixes
• #5210: Modernise api-builder runtime tests: models_test.js

• #6135: Server fails to start without @axway/api-builder-admin on Node.js 12 or 13
Release Notes
• #6099: Previously, when https traffic is enabled there was no way to disable http traffic. Now, new
configuration option - http.disabled - can be used to disable http traffic. See deprecation [D038].
• #6135: Previously, API Builder would crash on startup when running a production install without
@axway/api-builder-admin on Node.js 12 or 13. Now, the service starts as expected.
Deprecations
These are the deprecations introduced in this release. Click here for a list of all deprecations.
• [D038] Port: Usage of port in the project configuration has been deprecated. Use http.port instead.
See Project Configuration.
Updated modules
Updated plugins
• @axway/api-builder-plugin-dc-mongo@1.1.12
• @axway/api-builder-plugin-dc-mssql@1.1.3
• @axway/api-builder-plugin-dc-mysql@2.2.14
• @axway/api-builder-plugin-dc-oracle@3.0.3
• @axway/api-builder-plugin-fn-base64@2.1.1
• @axway/api-builder-plugin-fn-dot@2.1.1
• @axway/api-builder-plugin-fn-json@2.0.14
• @axway/api-builder-plugin-fn-restclient@2.0.17
• @axway/api-builder-plugin-fn-swagger@2.6.12
• @axway/api-builder-plugin-fn-mustache@1.0.3
• axway-flow-sdk@3.4.2

Known Issues
ENOTFOUND errors.
{
"swagger": "2.0",
"paths" {
"x-path": {
"get": {}
},
"/find": {
},
"/search": {
}
}
}

{

"success": false,
}
by the flow.
".".
API Builder Standalone - 22 November 2019

API Builder Standalone - Ennis
Summary
• Upgrade
• Features
• Fixes

• Release Notes
• Deprecations
• Updated Modules
• Plugins
• Known Issues
Upgrade
npm update
Features
• #5643: Filter get-catalog results to only Unified Catalog entries

• #6092: Fix sorting algorithm for bound paths
Fixes
• #6121: API Key should be logged at debug, not info

• #6126: Builder CLI - Filter catalog items by swagger v2 type
Release Notes
• #5643: The amplify builder CLI now supports filtering when downloading the API Catalog.
• #6092: Previously, APIs would be sorted and bound in an inconsistent order based on the load order
and sort property, Node.js version, and other factors. Now, APIs will be always bound in a consistent
order. Removed the explicit maximum supported Node.js version limitation. See deprecation [D037].
• #6121: Previously, on server startup the application's API Key was logged at the 'info' log level. Now,
the API Key is logged at the 'debug' log level.
• #6126: Previously, Amplify Builder CLI fetched from the API Catalog all the available catalog items.
Now, the CLI fetches only the items with API type.
Deprecations
• [D037] Sort: Creating an API or Route with the sort property is deprecated in favor of a more robust
internal sort mechanism.
Updated modules
Updated plugins

Known Issues
ENOTFOUND errors.
{
"swagger": "2.0",
"paths" {
"x-path": {
"get": {}
},
"/find": {
},
"/search": {
}
}
}


{
"success": false,
}
by the flow.
".".

API Builder Standalone - Darwin
Summary

• Upgrade
• Fixes
• Release Notes
• Updated Modules
• Plugins
• Known Issues
Upgrade
npm update
Fixes
• #6105: Fix generation of Models from schemas with a field called 'id' that is not a PK
• #6106: Update amplify-api-builder-cli to remove mbs
Release Notes
• #6105: Previously, Model fields named 'id' were reserved for Primary Keys only, and any field using this
name would cause an error to be thrown. Now, Models can have non-PK fields named 'id'.
Updated modules
Updated plugins
Known Issues
ENOTFOUND errors.

{
"swagger": "2.0",
"paths" {
"x-path": {
"get": {}
},
"/find": {
},
"/search": {
}
}
}

{
"success": false,
}
by the flow.

".".
API Builder Standalone - 11 October 2019

API Builder Standalone - Cairo
Summary
• Upgrade
• Fixes
• Release Notes
• Deprecations
• Updated Modules
• Plugins
• Known Issues
Upgrade
npm update

Fixes
• #1835: Deprecate the APIBuilder.remove* methods

• #4926: Deprecate APIBuilder.debug
• #4927: Deprecate APIBuilder.app.locals
• #5246: Adjust custom inspect functions to work with newer Node versions
• #6019: Deprecate Model.reduce
• #6020: Deprecate Model.prototype.extend (extend a model instance)
• #6026: Document maximum supported Node.js version (10.x)
• #6028: Deprecate Codeblocks
• #6038: Always use full Connector name in Swagger operationIDs
• #6053: Deprecate Model "prefix"
• #6072: Deprecate @axway/api-builder-react-engine
• #6079: Deprecate Model.define
• #6082: Document deprecated Logger functions
• #6084: Deprecate APIBuilder.get
• #6085: Deprecate APIBuilder.pluralize and singularize
• #6086: Deprecate Model.fields[name].optional and API.parameters[name].optional
• #6097: Enabling plugin authentication denies access to /console
Release Notes
• #1835: APIBuilder.removeModel, APIBuilder.removeConnector, APIBuilder.removeBlock,

APIBuilder.removeAPI, APIBuilder.removeAPIByFilename, APIBuilder.removeRoute functions are
deprecated, and will now generate a deprecation warning. They will be removed in a future version of
the product. See deprecations [D018], [D019], [D020], [D021], [D022], [D023].
• #4926: APIBuilder.debug is deprecated, and will now generate a deprecation warning. It will be
removed in a future version of the product. See deprecation [D027].
• #4927: APIBuilder.app.locals is deprecated, and will now accessing appc_external_url,

appc_external_apidoc_path_legacy, appc_external_apidoc_path, or appc_external_apidoc_url will
generate a deprecation warning. They will be removed in a future version of the product. See
deprecation [D026].
• #5246: Previously, using util.inspect to inspect API Builder components such as the API Builder
app, models, or connectors, would emit the deprecation message "[DEP0079]
DeprecationWarning: Custom inspection function on Objects via .inspect() is
deprecated" with Node.js >10.0.0 and returns a different string with Node.js >11.0.0. Now, the
deprecation warning is no longer emitted.
• #6019: Model instance reduce and APIBuilder.Model.reduce functions are deprecated, and will
now generate a deprecation warning. They will be removed in a future version of the product. See
deprecation [D017].
• #6020: Extending a model instance (Model.prototype.extend) is deprecated and will now generate a
deprecation warning. It will be removed in a future version of the product. Instead, use Model.extend.
See deprecation [D025].

• #6026: The maximum supported Node.js version (10.x) is now specified within the docs and
package.json
• #6028: Codeblocks are deprecated, and will now generate a deprecation warning. They will be
• #6038: Previously, operationId fields of generated Model APIs using Connectors with aliases
prefixed with "appc." would contain the Connector alias with this prefix removed. Now, operationId
fields will contain the full Connector alias.
• #6053: Creating Models with the prefix property has been deprecated and will generate a
deprecation warning on use. See deprecation [D024].
• #6072: @axway/api-builder-react-engine has been deprecated and is no longer supported. See

deprecation [D029].
• #6079: Model.define is deprecated, and will now generate a deprecation warning. It will be removed in
a future version of the product. See deprecation [D016].
• #6082: APIBuilder.logger.stripColors is deprecated, and will now generate a deprecation

warning. It will be removed in a future version of the product. See deprecation [D033].
• #6082: Logger.createDefaultLogger is deprecated, and will now generate a deprecation

• #6082: Logger.createRestifyLogger is deprecated, and will now generate a deprecation

• #6084: APIBuilder.get is deprecated, and will now generate a deprecation warning. It will be
• #6085: APIBuilder.pluralize is deprecated, and will now generate a deprecation warning. It will
be removed in a future version of the product. See deprecation [D031].
• #6085: APIBuilder.singlularize is deprecated, and will now generate a deprecation warning. It

will be removed in a future version of the product. See deprecation [D032].
• #6086: Using the optional property on Model fields and API parameters has been deprecated and
will generate a deprecation warning on use. See deprecation [D021].
• #6097: Previously, when plugin authentication was configured and the mechanism did not define a
matchURL method, the server would incorrectly require authentication for public paths. Now, public
paths are accessible when using plugin authentication.
Deprecations
• [D016] Model.define: Model.define is deprecated and will be removed in a future version of the
product. Use Model.extend or APIBuilder.createModel instead.
• [D017] Model instance reduce and APIBuilder.Model.reduce: Reducing a Model instance (i.e.
Model.prototype.reduce) and APIBuilder.Model.reduce are deprecated and will be
removed in a future version of the product. For more information on how to be prepared for the
change, refer to Removal of the Model instance reduce and APIBuilder.Model.reduce functions.

• [D018] APIBuilder.removeModel: APIBuilder.removeModel is deprecated and will be removed in a

future version of the product.
• [D019] APIBuilder.removeConnector: APIBuilder.removeConnector is deprecated and will be

removed in a future version of the product.
• [D020] APIBuilder.removeBlock: APIBuilder.removeBlock is deprecated and will be removed in a

• [D021] APIBuilder.removeAPI: APIBuilder.removeAPI is deprecated and will be removed in a

• [D022] APIBuilder.removeAPIByFilename: APIBuilder.removeAPIByFilename is deprecated and

will be removed in a future version of the product.
• [D023] APIBuilder.removeRoute: APIBuilder.removeRoute is deprecated and will be removed in a

• [D024] Model prefix: Creating a Model with the prefix property is deprecated and will be removed in
a future version of the product. See Removal of Model prefix.
• [D025] Model.prototype.extend: Extending a model instance (i.e. Model.prototype.extend) is

deprecated and will be removed in a future version of the product. Use Model.extend instead.
• [D026] APIBuilder.app.locals: APIBuilder.app.locals properties appc_external_url,

appc_external_apidoc_path_legacy, appc_external_apidoc_path, or
appc_external_apidoc_url are deprecated and will be removed in a future version of the
product.
• [D027] APIBuilder.debug: APIBuilder.debug is deprecated and will be removed in a future version

of the product.
• [D028] Codeblocks: Codeblocks are deprecated and will be removed in a future version of the product.
For more information on how to be prepared for the change, refer to Removal of Codeblocks.
• [D029] @axway/api-builder-react-engine: @axway/api-builder-react-engine is deprecated and will not

receive any updates. If you are currently using Web Routes, consider switching to another modern web
application architecture for your front end that consumes API Builder Service APIs.
• [D030] APIBuilder.get: APIBuilder.get is deprecated and will be removed in a future version of the
product.
• [D031] APIBuilder.pluralize: APIBuilder.pluralize is deprecated and will be removed in a future

version of the product. Use the pluralize module instead.
• [D032] APIBuilder.singularize: APIBuilder.singularize is deprecated and will be removed in a

future version of the product. Use the pluralize module instead.
• [D033] APIBuilder.logger.stripColors: APIBuilder.logger.stripColors is deprecated and will

be removed in a future version of the product.
• [D034] Model.fields[name].optional and API.parameters[name].optional: Using the optional

property on Model fields and API parameters is deprecated and will be ignored in a future version of
the product. Use the required property instead.

• [D035] Logger.createDefaultLogger: The static function Logger.createDefaultLogger is

deprecated and will be removed in a future version of the product.
• [D036] Logger.createRestifyLogger: The static function Logger.createRestifyLogger is

deprecated and will be removed in a future version of the product.
Updated modules
Updated plugins
Known Issues
ENOTFOUND errors.
{
"swagger": "2.0",
"paths" {
"x-path": {
"get": {}
},
"/find": {
},
"/search": {
}
}
}


{
"success": false,
}
by the flow.

".".
API Builder Standalone - 27 September 2019

API Builder Standalone - Barcelona
Summary
• Upgrade
• Features
• Fixes
• Release Notes
• New Deprecations
• Updated Modules
• Known Issues
Upgrade
npm update
Features
• #5994: Add API for arrowPing.json to improve ARS compatibility

• #6024: Connector models generate friendlier API
• #6068: Support development environment file
Fixes
• #6036: MBS connector errors leave API Builder hanging due to uncleared interval
• #6075: Save and mock admin API swallows up errors
Release Notes
• #5994: Improved compatibility with ARS by including the default ARS healthcheck endpoint "/
arrowPing.json". This behaves identically to "/apibuilderPing.json" and can be overridden in the same
way.

• #6024: Previously, API Builder would generate API for models that originate from connectors in a way
that included a slash, e.g. "oracle/user", and would generate an API that URL encodes "oracle/user"
as /api/oracle%2Fuser/query. Now, the slash between the connector name and model name is
preserved and will render as /api/oracle/user/query. See deprecation #15.
• #6036: Previously, if data connectors failed to connect to a data source, the actual error may be lost
behind a "callback called twice" error. Now, the original error is kept and the callback is not called
twice.
• #6068: API Builder now supports the ability to load a .env file containing environment variables to
assist in running services with development-specific values. New projects are scaffolded with an
example .env file in the ./conf directory. For further information, see: Environmentalization Guide.
• #6068: Projects will no longer be scaffolded with nyc as a dependency.
• #6075: Previously, errors during Endpoint creation and mocking may be swallowed up and unclear.
Now, the cause of the error is logged.
New Deprecations
• #15 Model names which are prefixed with their connector name (in other words, oracle/user) will no
longer have the slash encoded as %2F in auto-generated API paths. This will be the default behavior
for all new services. For information on how to be prepared for the change, and to start using the new
behavior now, refer to Change in the way model name with connector prefix is encoded in paths.
Updated modules
Known Issues
ENOTFOUND errors.
{
"swagger": "2.0",
"paths" {
"x-path": {
"get": {}
},
"/find": {
},
"/search": {
}

}
}

{ "message": "Invalid Value for Find By ID: "YOUR_STRING_PK_NAME",

"success": false, "request-id": "c118f187-2090-4a68-b939-37367ac55b80" }
by the flow.

".".
API Builder Standalone - 30 August 2019

API Builder Standalone - Akita
Summary
• Upgrade
• Features
• Fixes
• Release Notes
• Updated Modules
• Known Issues
Upgrade
npm update
Features
• #5674: Fix Memory connector to return collections
Fixes
• #6005: Ignore 'unsel' in Connector queries when 'sel' is provided
Release Notes
• #5674: Previously, the Memory connector would return an array of objects instead of a Collection of
objects when calling query or distinct. Now, the Memory connector correctly returns a Collection.
• #5674: Previously, the Memory connector would return an array of objects that contained all fields
when performing a distinct operation, instead of objects containing only the distinct field. Now, the
Memory connector returns a Collection of distinct objects that contain only the distinct field.

• #6005: Previously, some Connectors were executing queries incorrectly considering both sel and
unsel. Now, all Connectors will ignore unsel when sel is provided.
Updated modules
Updated plugins
• @axway/api-builder-plugin-dc-mbs@0.1.0
Known Issues
ENOTFOUND errors.
{
"swagger": "2.0",
"paths" {
"x-path": {
"get": {}
},
"/find": {
},
"/search": {
}
}
}



by the flow.
".".

API Builder Standalone - Zams

Summary
• Upgrade
• Features
• Fixes
• Release Notes
• Updated Modules
• Plugins
• Known Issues
Upgrade
npm update
Features
• #5893: Replace doT with mustache flow-node
Fixes
• #5679: arrow-orm fails on $like with val.replace error
Release Notes
• #5679: Previously, attempting to query a model where a field was filtered using $like and a non-string
value (e.g. $like: 1) would cause a TypeError: val.replace is not a function exception to
be thrown. Now, $like handles non-string values.
• #5893: Previously, API Builder projects were bundled with @axway/api-builder-plugin-fn-dot which was
used to create string templates and objects, but it had a dependency with a security vulnerability
(doT). Now, the dependency is removed and projects are bundled with @axway/api-builder-plugin-fn-
mustache for string templates, and the recommendation is to use @axway/api-builder-plugin-fn-
javascript for objects.
Updated modules
Updated plugins

Known Issues
ENOTFOUND errors.
{
"swagger": "2.0",
"paths" {
"x-path": {
"get": {}
},
"/find": {
},
"/search": {
}
}
}
• #4595: When using a distinct API backed by the Memory connector and passing a field which
does not exist on the model, the first record is returned instead of an error.



by the flow.
".".

API Builder Standalone - Yako
Summary
• Upgrade
• Features
• Fixes
• Release Notes

• Updated Modules
• Plugins
• Known Issues
Upgrade
npm update
Features
• #5892: Support auto-select of initial parameter type for flow-nodes

• #5924: Add Mustache Flow-Node
• #5956: Include JavaScript Flow-Node in all new applications
Fixes
• #4811: Fix Bootstrap XSS vulnerability

• #5912: Fix lodash.merge prototype pollution
• #5920: Update .dockerignore file with .git and coverage
• #5954: Modifying outputs in the Flow Editor causes value to change to "jsonpath"
• #5957: Fix marked Regular Expression Denial of Service (ReDoS) vulnerability
Release Notes
• #4811: Previously, RetireJS security scans of API Builder would report that it was using a vulnerable
dependency on bootstrap@3.3.7. Now, the dependency is no longer reported.
• #5892: Flow-nodes now support defining an initial type for parameters in the UI, other than always
being a selector. For example, template fields could have their initialType set to string. See
Axway Flow SDK for more information.
• #5912: Previously, when using "npm install" on an API Builder project, npm would alert that
"lodash.merge" had a high alert for Prototype Pollution ([https://nodesecurity.io/advisories/1067]).
Now, the alert has been resolved by removing the dependency.
• #5920: Previously, the .dockerignore file that comes with a scaffolded API Builder service did not
include .git, coverage, and .nyc_output folders. Now, those folders are added.
• #5924: The UI now renders a specialized Mustache editor with syntax highlighting for flow-node
parameters which are defined with "format": "mustache" and "type": "string" in their schema.
• #5954: Previously, there was a regression which meant flow-node outputs were un-editable, causing
the value to always change to "jsonpath". Now, outputs can be edited again.
• #5956: The API Builder CLI will now include the JavaScript flow-node in all new projects.
• #5957: Previously, when using "npm install" on an API Builder project, npm would alert that "marked"
had a low alert for Regular Expression Denial of Service ([https://www.npmjs.com/advisories/1076]).
Now, the alert has been resolved by updating the dependency.

Updated modules
Updated plugins
• @axway/api-builder-plugin-fn-mustache@1.0.1
Known Issues
ENOTFOUND errors.
{
"swagger": "2.0",
"paths" {
"x-path": {
"get": {}
},
"/find": {
},
"/search": {
}
}
}



by the flow.

".".
API Builder Standalone - 19 July 2019

API Builder Standalone - Xapuri
Summary
• Upgrade
• Features
• Fixes
• Release Notes
• Updated Modules
• Plugins
• Known Issues
Upgrade
npm update
Features
• #5891: Add editor for 'javascript' format Flow-Node parameters
Fixes
• #5922: Fix incorrect examples when testing Endpoints
Release Notes
• #5891: The UI now renders a specialized javascript editor with syntax highlighting for Flow-Node
parameters which are defined with "format": "javascript" and "type": "string" in their
schema.
• #5891: Flow-nodes now support defining wrapper text for multiline and javascript format
parameters. The wrapper text is displayed in the parameter editor but will not be part of the value
when saved in the flow. This is useful for when context or comments are needed. For more
information, refer to Flow-nodes.
• #5922: Previously, the example body that was shown when testing Endpoints could be incorrect and
include schema snippets such as $ref or anyOf. Now, the example will better represent the expected
body and will not include these schema snippets.

Updated modules
Updated plugins
Known Issues
ENOTFOUND errors.
{
"swagger": "2.0",
"paths" {
"x-path": {
"get": {}
},
"/find": {
},
"/search": {
}
}
}



by the flow.
".".


API Builder Standalone - Wellington
Summary
• Upgrade
• Features
• Release Notes
• Updated Modules
• Plugins
• Known Issues
Upgrade
npm update
Features
• #5823: Support Docker HEALTHCHECK

• #5829: Add process.env.PORT to conf/default.js
Release Notes
• #5823: Added HEALTHCHECK to the Dockerfile created in new API Builder services. When the service
is built using Docker, it will be polled every 30 seconds to check if it is running and healthy.
• #5829: Previously, API Builder projects had configuration which hard-coded port 8080 by default.
Now, while API Builder projects still default to 8080, the PORT environment variable can be used to
specify a different port. e.g. PORT=8081 npm start which allows for a better out-of the-box
experience for containerization.
Updated modules
Updated plugins

Known Issues
ENOTFOUND errors.
{
"swagger": "2.0",
"paths" {
"x-path": {
"get": {}
},
"/find": {
},
"/search": {
}
}
}



by the flow.
".".
API Builder Standalone - 21 June 2019

API Builder Standalone - Valencia
Summary
• Upgrade
• Fixes
• Release Notes
• Updated Modules

• Known Issues
Upgrade
npm update
Fixes
• #5620: Fix string-based model queries on dates, booleans and number fields
• #5819: Fix invalid JSON Schema and Swagger documentation generated for models that have PK of
type date
Release Notes
• #5620: The Memory connector has been updated to use Version 2 of the "mingo" dependency for data
storage and queries. This fixes multiple issues, including problems finding and updating objects and
dates. Note that trying to use any unknown operators, such as $foo, when querying on the Memory
connector will result in an error.
• #5620: Previously, there were issues when using strings to query date, number, and boolean fields on
findAndModify, query, count, and distinct model methods. Queries such as '\{ "DATE": { "$gt":
"2020-10-10" } }' would fail to work causing database errors. Now, the values in queries are interpreted
as the correct type when interacting with the underlying database.
• #5819: Previously, the service would fail to start when loading a Model with a Date as a Primary Key.
Now, the service will start.
• #5819: Previously, when generating Swagger documentation for your service, certain parameters
which are Date fields internally would be represented using type: 'string' and format: 'date' or 'date-
time'. This format didn't allow for the variety of date formats that work when calling the API, so certain
inputs would be rejected if validated against the Swagger documentation. Now, the format has been
removed, allowing any date format to be provided.
Updated modules
Known Issues
ENOTFOUND errors.

{
"swagger": "2.0",
"paths" {
"x-path": {
"get": {}
},
"/find": {
},
"/search": {
}
}
}


by the flow.

".".
API Builder Standalone - 7 June 2019

API Builder Standalone - Utopia
Summary
• Upgrade
• Updated Modules
• Plugins
• Known Issues
Upgrade
npm update
Updated modules

Updated plugins
Known Issues
ENOTFOUND errors.
{
"swagger": "2.0",
"paths" {
"x-path": {
"get": {}
},
"/find": {
},
"/search": {
}
}
}



by the flow.
".".
API Builder Standalone - 24 May 2019

API Builder Standalone - Turin

Summary
• Upgrade
• Fixes
• Release Notes
• Updated Modules
• Plugins
• Known Issues
Upgrade
npm update
Fixes
• #5742: Replace doT where possible in api-builder-plugins to reduce vulnerability warnings

• #5775: Fix Swagger generation for services with models containing slashes
• #5795: Count on a composite model having a 'where' condition is ignored
Release Notes
• #5742: Updated the versions of base64, dot, and json plugins which are included with new API Builder
projects.
• #5775: Previously, models containing slashes were rendered in to the API Builder application's
Swagger document's definitions as URI encoded slash, e.g. "model%2Ffoo". This was incorrect, and
while most model names would validate as Swagger, model names that contained a slash would fail
validation. Now, model Swagger definitions are no longer URI encoded.
• #5795: Previously, attempting to count records on a composite model with a where clause would
return a count for all records (unfiltered). Now, count will filter and count records using the where
clause.
Updated modules
Updated plugins

Known Issues
ENOTFOUND errors.
{
"swagger": "2.0",
"paths" {
"x-path": {
"get": {}
},
"/find": {
},
"/search": {
}
}
}



by the flow.
".".
API Builder Standalone - 26 April 2019

API Builder Standalone - Sofia

Summary
• Upgrade
• Fixes
• Release Notes
• Updated Modules
• Plugins
• Known Issues
Upgrade
npm update
Fixes
• #5650: @axway/amplify-api-builder-cli readme mentions wrong package

• #5662: Fix issue corrupting files and stacking reloads on concurrent calls to Admin APIs
Release Notes
• #5650: Previously, the readme for @axway/amplify-api-builder-cli incorrectly referenced itself as

@axway/amplify-builder-cli. Now, this is corrected.
• #5662: Previously, API Builder was not able to handle concurrent calls to admin APIs which modified
the service, for example, edit model, and could corrupt the file being written. Multiple reloads could
also happen subsequently. Now, admin APIs which modify the server cannot be called concurrently.
• #5662: Previously, API Builder would allow API calls while the server was reloading and in an unstable
state. Now, during reload requests will respond with 503.
Updated modules
Updated plugins
Known Issues
ENOTFOUND errors.

{
"swagger": "2.0",
"paths" {
"x-path": {
"get": {}
},
"/find": {
},
"/search": {
}
}
}



by the flow.
".".
• #5685: The following packages have a dependency on the doT npm module, which is vulnerable to
command injection (see advisory #798): @axway/api-builder-plugin-fn-dot, @axway/api-builder-plugin-
fn-base64, @axway/api-builder-plugin-fn-restclient, @axway/api-builder-plugin-fn-swagger, and axway-
flow-sdk.
API Builder Standalone - 12 April 2019

API Builder Standalone - Raga
Summary
• Upgrade
• Breaking Changes
• Fixes

• Release Notes
• Updated Modules
• Plugins
• Known Issues
Upgrade
npm update
Major Change
• #5583: New API Builder CLI for AMPLIFY platform
Fixes
• #5626: Concurrent writes to same model file causes server to crash

• #5641: Error "Not possible to find intersection inside of the rectangle" when saving flow
Release Notes
• #5626: Previously, creating multiple models very quickly could cause model file corruption. Now,
concurrency is handled correctly.
• #5641: Previously, using Save and exit in the Flow editor would successfully save the Flow and emit a
console error, "Not possible to find intersection inside of the rectangle". Now, no error is emitted.
Updated modules
Updated plugins
Known Issues
ENOTFOUND errors.
{
"swagger": "2.0",
"paths" {
"x-path": {

"get": {}
},
"/find": {
},
"/search": {
}
}
}


by the flow.

".".
API Builder Standalone - 29 March 2019

API Builder Standalone - Quebec
Summary
• Upgrade
• Features
• Fixes
• Release Notes
• Updated Modules
• Plugins
• Known Issues
Upgrade
npm update

Features
• #5440: Support flow-node change of parameter name

• #5602: Fix Model responses to include null fields
Fixes
• #5547: Fix crash when generating Endpoints for Models with names starting with colon
• #5556: Fix an issue displaying long default values of parameters in the Flow editor
• #5577: Fix crashes on concurrent restarts
Release Notes
• #5440: Previously, when using updated Flow-nodes (or Swagger documents using the swagger plugin)
with renamed or removed parameters, the Flow would be invalid and not editable or fixable without
making manual edits. Now, these issues can be resolved in the Flow editor.
• #5547: Previously, generating endpoints for models with names starting with a colon ":" would emit an
"Error loading endpoint" error on startup and exit. Now, generate endpoints works as expected. See
deprecation #14.
• #5556: Previously, a regression caused the default value of parameters in the Flow editor to render in
an unusable format such as [Object object] when the value was an object or array. Now, objects and
arrays will be rendered in a JSON stringified format.
• #5577: Previously, the server would crash on concurrent reloads. Now, the server will process the first
reload, and ignore reloads that occur concurrently.
• #5602: Previously, null fields from models would not be returned in responses such as findAll. Now,
they will be included in the response. missing or undefined fields will behave the same. Use this
feature is limited by connector support for null fields. See deprecation #13.
New Deprecations
• #13: Queries on Models which have fields with null values can now return that field in the response
rather than hiding the field. Support for this behavior is dependent on the connector being used. This
will be the default behavior for all new services. For information on how to be prepared for the change,
and to start using the new behavior now, refer to Change in the way null fields are returned in Models.
• #14: Model names are now URI encoded as per RFC-3986 and the APIs that are created from Generate
endpoints for models will bind to their URI equivalent. This will be the default behavior for all new
services. For information on how to be prepared for the change, and to start using the new behavior
now, refer to Change in the way model name is encoded in Swagger.
Updated modules
Updated plugins

Known Issues
ENOTFOUND errors.
{
"swagger": "2.0",
"paths" {
"x-path": {
"get": {}
},
"/find": {
},
"/search": {
}
}
}



by the flow.
".".

API Builder Standalone - Phoenix
Summary
• Upgrade
• Fixes
• Release Notes
• Updated Modules

• Plugins
• Known Issues
Upgrade
npm update
Fixes
• #5263: Log Plugin load errors and stack traces

• #5469: Fix names for Model Flow-Nodes when the Model name starts with the Connector name
• #5573: Flow-node outputs are missing schema in Flow Editor
• #5585: Improve the UI's detection of server restarts
Release Notes
• #5263: Previously, when a Plugin fails to load, the stack trace of the error was hidden. Now, the stack
trace will be logged at debug level.
• #5469: Previously, Flow-Nodes for models may have broken names when the model name began with
the connector name. For example, a model called "compositeFoo" created with the composite
connector would have the name "oo". And a model called "composite" would have no name to display.
Now, the Flow-Node names retain the original model name.
• #5573: Previously, a regression caused outputs in the Flow Editor to have a missing schema popover.
Now, the schema will be displayed as previously.
• #5585: Previously, API Builder UI would sometimes fail to detect when the server finished restarting
after updates (e.g. after modifying configuration) and either take a long time to detect (e.g. 40
seconds), or sometimes timeout with a "Restart failure". Now, API Builder will detect the server
restarted within three seconds of a restart.
Updated modules
Updated plugins
Known Issues
ENOTFOUND errors.

{
"swagger": "2.0",
"paths" {
"x-path": {
"get": {}
},
"/find": {
},
"/search": {
}
}
}



by the flow.
".".

API Builder Standalone - Osaka
Summary
• Upgrade
• Features
• Fixes
• Release Notes
• Updated Modules

• Plugins
• Known Issues
Upgrade
npm update
Features
• #5425: Support the ability to fix errors in Flows when a Flow-Node method ID changes
• #5454: Add the ability to execute Flows from within the Flow editor
• #5484: Support collapsing the Flow-Nodes panel in the Flow editor
Fixes
• #5499: Create model with name containing invalid character will kill the server
• #5516: Provide model flow-node outputs and methods with friendly names
• #5526: Suppress "Translate this page?" prompt on Chrome
• #5539: API Example for web.js is incorrect
• #5545: HIGH vulnerability - All versions of `handlebars` are vulnerable to Prototype Pollution
• #5549: Moderate vulnerability lodash
• #5551: Changed field name gets reverted on composite model
• #5578: Update @axway/requester version in Swagger plugin
Release Notes
• #5425: Previously, it was difficult to know how to fix a Flow in the editor when a Flow-Node method
which was in changed, rendering the Flow invalid. Now, the editor has been improved to show the
friendly names of missing methods and outputs, and provide a useful error message.
• #5425: Previously, Flows would not be edited on disk when API Builder performed any updates, and
would require a manual edit before the changes persisted. Now, Flows will automatically be edited on
disk if and when API Builder makes any changes.
• #5454: Added the ability for Flows to be provided with parameters and executed without having to
leave the Flow Editor. Click the Bug icon to start playing!
• #5484: The Flow-Nodes panel on the left of the Flow editor can now be collapsed to make more space
to edit Flows.
• #5499: Previously, creating a Model with a name having any reserved ExpressJS regular expression
characters ?, +, *, (,or ) could cause the server to fail to start, or could inadvertently cause a bound
API to match unexpectedly. Now, the server will start and the API will match as expected. See
deprecation 12.
• #5516: Previously, the outputs and methods of Model flow-nodes did not have user-friendly names in
the UI. Now, the displayed names are more user-friendly.

• #5526: Previously, the Chrome browser offered to translate API Builder pages. Now, the Chrome
browser will no longer offer to translate pages.
• #5539: Previously, API Endpoints examples for node.js and web.js were incorrect. Now, the
displayed examples compile and are syntactically correct with respect to inputs, authentication, and
responses.
• #5545: Previously, API Builder had a dependency on handlebars library, which had a security
vulnerability 755 reported against it. Now, API Builder is using a patched version of handlebars that
fixes the vulnerability.
• #5549: Previously, API Builder had a dependency on lodash and express-ipfilter libraries, which had a
security vulnerabilities 782 and 577 reported against them, respectively. Now, API Builder is using a
patched version of lodash that fixes the vulnerability, and removed the express-ipfilter dependency.
• #5549: Your API Builder projects have a direct dependency on a vulnerable nyc, used for code
coverage. You should update nyc to the latest version (13.3.0 at the time of this release).
• #5551: Previously, when editing a composite model and change the name of a field, the field name
gets reverted back to its original. Now, the changed field name persists through any other edit.
New Deprecations
• #12: Model names are now URI encoded as per RFC-3986 and the APIs that are auto-generated for
models will bind to their URI equivalent. This will be the default behavior for all new services. For
information on how to be prepared for the change, and to start using the new behavior now, refer
to Change in the way model name is encoded in URI.
Updated modules
Updated plugins
Known Issues
ENOTFOUND errors.

{
"swagger": "2.0",
"paths" {
"x-path": {
"get": {}
},
"/find": {
},
"/search": {
}
}
}


by the flow.

".".
API Builder Standalone - 15 February 2019

API Builder Standalone - Naples
Summary
• Upgrade
• Features
• Fixes
• Release Notes
• Updated Modules
• Plugins
• Known Issues
Upgrade
npm update

Features
• #5470: Support YAML endpoints and import API
Fixes
• #5479: Show code examples for using Endpoints

• #5481: Headers should have x-frame-options and x-xss-protection for security
• #5502: Correct documentation in default.js in respect to ldap authentication
Release Notes
• #5470: Previously, API Builder only supported JSON Swagger endpoint documents, or when imported
via Import API. Now, API Builder also supports YAML endpoint documents.
• #5479: Previously, there were no code examples for testing endpoints in Admin UI. Now, code
examples for testing endpoints have been added.
• #5481: Previously, API Builder did not respond with recommended HTTP security headers for x-
frame-options, x-content-type-options, cache-control, and x-xss-protection. Now,
API Builder responds with these HTTP headers.
• #5502: Previously, the documentation for configuring ldap authentication within conf/default.js
was incorrect. Now, the documentation for that aspect is corrected.
Updated modules
Updated plugins
Known Issues
ENOTFOUND errors.
{
"swagger": "2.0",
"paths" {
"x-path": {
"get": {}
},
"/find": {

},
"/search": {
}
}
}


by the flow.

API Builder Standalone - 1 February 2019

API Builder Standalone - Melbourne
Summary
• Features
• Fixes
• Release Notes
• Updated Modules
• Plugins
• Known Issues
Features
• #5436: Support Parameter Groups in flow-nodes and Flow editor

• #5478: Support apikey authentication in API Doc and Test for Endpoints
Fixes
• #5442: Fix CORS for API with path parameters

• #5448: Apply CORS to static resources
• #5474: Update Dockerfile with correct file permissions in template
• #5485: Regression in Swagger plugin validation
Release Notes
• #5436: Previously, all parameters in the flow editor were rendered in a single group. Now, related
parameters can be grouped together in collapsible panels by using the axway-flow-sdk.
• #5442: Previously, CORS requests were not working correctly on APIs that are bound on paths with
parameters. Now, CORS is behaving correctly for these cases.

• #5448: Previously, if CORS was enabled in the application, the static files were not served with the
correct headers. Now, the appropriate headers are attached.
• #5474: Previously, when building a Docker image using the default Dockerfile, there was a failure on
macOS Mojave due to insufficient rights when copying the application into the app directory, and OS
would succeed to create the container, but had incorrect file permissions that would disallow write.
Now, new services are created with an updated Dockerfile which allows the image to be created
successfully.
• #5478: Previously, the Test API functionality for endpoints would not work correctly when the service
auth strategy was changed from 'basic'. Now, it works with the 'apikey' strategy too.
Updated modules
Updated plugins
Known Issues
ENOTFOUND errors.
{
"swagger": "2.0",
"paths" {
"x-path": {
"get": {}
},
"/find": {

},
"/search": {
}
}
}


by the flow.

API Builder Standalone - 18 January 2019

API Builder Standalone - Lisbon
Summary
• Features
• Fixes
• Release Notes
• Updated Modules
• Plugins
• Known Issues
Breaking Changes
• #5264: The configured authentication strategy is now always applied to paths under the configured
apiPrefix. This was introduced as a security fix will break services relying on custom plugins with
matchURL functions that intend to bypass auth on certain APIs. See deprecation 10.
Features
• #5125: Add "Home" link functionality to Axway logo and API Builder text in the header
• #5180: Support the user in managing OAuth2 credentials for devops
• #5264: Provide clearer and more explicit HTTP authentication
Fixes
• #5337: Limit graph scaling in flow editor

• #5404: RegEx DoS attack on markdown rendering engine
• #5412: OAuth 2.0 toast is not showing

• #5419: Deprecate web routes

• #5441: Create model with name containing invalid character will kill the server
Release Notes
• #5125: Previously, the the Axway logo and the API Builder text in the header were not interactable.
Now, they act as hyperlinks and take you to the Summary page.
• #5180: Previously, the credential cards did not provide user access to refresh and obtain tokens. Now,
you can refresh and obtain tokens from the credential cards.
• #5264: Previously, requests to non-existing resources on apiPrefix did not have authentication.
Now, all requests to apiPrefix must pass authentication. Added config.accessControl settings
to clarify authentication and ensure that HTTP authentication is applied to all paths bound
on apiPrefix and that any path not on apiPrefix, be required to be explicitly public. This
change deprecates the use of matchURL in authentication plugins and deprecates the configuration
settings for APIKeyAuthPlugin and APIKeyAuthType. For additional information, refer to Change
in the way of handling authentication and authentication plugins. See deprecation 10.
• #5337: Previously, it was possible to lose the flow in the flow editor while zooming in or out. Now,
there is a limit to how far you can zoom.
• #5404: Previously, API Builder used appc-marked for its markdown engine. Now, it is using marked .
• #5412: Previously, the toast notification was shown very fast and was not visible to the user. Now, the
notification is clearly visible.
• #5419: Previously, API Builder registered all built-in rendering engines on startup by default. Now, API
Builder Web feature (routes in web/routes folder) has been deprecated so those rendering engines
are not registered by default but only if the web/routes folder exists. See deprecation 11.
• #5441: Previously, creating a model having a name with a single quote would succeed to create the
model, but would cause the application to fail to restart. Now, single quotes are escaped.
New Deprecations
• #10: Authentication has changed to make all paths secure, and public paths must be explicitly
declared. For information on how to be prepared for the change and to start using the new behavior
now, refer to Change in the way of handling authentication and authentication plugins.
• #11: API Builder Web is deprecated and will be removed in a future major version. If you are currently
using Web Routes, consider switching to another modern web application architecture for your front
end that consumes API Builder Service APIs.
Updated modules
Updated plugins

Known Issues
ENOTFOUND errors.
{
"swagger": "2.0",
"paths" {
"x-path": {
"get": {}
},
"/find": {
},
"/search": {
}
}
}



by the flow.
• #5448: CORS is not applied to static public web resources.

API Builder Standalone - Kobe
Summary
• Features
• Fixes
• Release Notes
• Updated Modules
• Plugins
• Known Issues

Features
• #5155: Add a nav badge to attract attention to credential errors

• #5357: Clarify next steps to take when viewing an invalid credential
Fixes
• #5388: Fix server error when rendering endpoints with path parameters defined using $ref pointers
• #5389: Endpoint headers are too verbose and unclear
• #5393: Importing API causes API Builder to exit
• #5394: Fix issue where API Key credential with an empty string value is resolved as null
Release Notes
• #5155: Introduced notification badges in the navigation menu to attract attention to Credentials that
need attention.
• #5357: Add documentation links for credentials that were invalid or incomplete to clarify next steps to
take.
• #5388: Previously, API Builder console would fail to render imported endpoints with path parameters
which were defined with a $ref pointer. Now, API Builder console will render these endpoints
correctly.
• #5389: Previously, messages describing "setting headers" would be logged out when getting a
response from an endpoint. These logs were unclear and displayed duplicate information as the
headers were also logged in the response. Now, these logs have been removed.
• #5393: Previously, Swagger files with invalid 'default' properties that do not match the type of the
property they refer to were loaded successfully and were failing during endpoint invocation. Now, such
Swagger files are not loaded successfully during initial file loading.
• #5394: Previously, an API key credential with a value of an empty string was resolved as 'null'. Now,
it is resolved as an empty string.
Updated modules
Updated plugins
Known Issues
ENOTFOUND errors.

{
"swagger": "2.0",
"paths" {
"x-path": {
"get": {}
},
"/find": {
},
"/search": {
}
}
}



by the flow.

API Builder Standalone - Jakarta
Summary
• Features
• Fixes
• Release Notes
• Updated Modules
• Plugins
• Known Issues
Features
• #5349: Release authorizations in flows feature.
Fixes
• #5353: Preserve authorization across reloads.

• #5374: Fix invalid deprecation URL for enableScopedConfig.

Release Notes
• #5349: Introducing support of authorization in API Builder flows. API Builder now manages credentials
and ensures tokens are kept valid. These credentials can be used directly by Swagger flow-nodes or
retrieved using the Authorization flow-node. For more information, see: API Builder Credentials.
• #5353: Previously, the system invalidated the authorized credentials on each system restart. Now, the
system preserves the authorized credentials on system restart as long as the credential has not been
updated within the corresponding configuration file.
• #5374: Previously, the enableScopedConfig deprecation warning had an invalid URL. Now, the
deprecation warning has the correct URL.
Updated modules
Updated plugins
Known Issues
ENOTFOUND errors.
path or paths defined by references the save will fail.
{
"swagger": "2.0",
"paths" {
"x-path": {
"get": {}
},
"/find": {
},
"/search": {
}
}
}
• #4528: Initializing new project with api-builder init 1234 where 1234 is any number, will throw
an ERR_INVALID_ARG_TYPE error rather than an "invalid npm package name".

plugin-dc-mongo) doesn't honor the value of the order parameter.
• #4752: The format of a distinct query's response depends on the type of connector.
• #4795: The MongoDB plugin @axway/api-builder-plugin-dc-mongo does not correctly support

primary keys that are not object identifiers. The MongoDB specification allows for primary keys of

• #4856: Passing in an invalid column name as a parameter to certain APIs generated from data
connectors will result in an exception being thrown rather than executing their callback with an error. A
by the flow.
name and can result in an invalid schema references in swagger flow-nodes.
project, unexpected things may occur. For example, the wrong flow or endpoint could be modified.
Using files with these types of names is not recommended.
Configuration file names. This is a result of an issue in react-router/history. https://github.com/
ReactTraining/history/issues/505

• #4966: API Builder will generate invalid Swagger for programmatic API in ./apis that bind to a path
other than the apiPrefix defined in the configuration. These API must be bound to the same root
path as is defined by apiPrefix.

API Builder Standalone - Istanbul
Summary
• Features
• Fixes
• Release Notes
• Updated Modules
• Plugins
• Known Issues
Features
• #5233: Ensure that plugins only receive plugin-specific configuration instead of the global service
configuration
• #5242: Support credential management and authorization in flows (pre-release feature)
Fixes
• #4890: Remove invisible column in Configuration list view

• #5121: The server fails to restart when saving a flow over HTTPS with SSL enabled
• #5165: Fix error when saving flow with special symbols in the filename
• #5234: Support using Credentials in flow-node parameters
• #5282: Improve localStorage detection in authorization dialog
• #5298: Fix error when importing an endpoint using a swagger document with path-level parameters.
• #5307: Fix swagger generation for services with models which have no primary key
• #5308: Support proxy settings on import API
• #5323: Replace invalid flow documentation link
• #5325: Fix spelling error in description of Set Context flow-node
Release Notes
• #4890: Previously, a column with no contents was displayed in the configuration list. Now, the column
has been removed.
• #5121: Previously, the sockets used by the server when SSL is enabled were not closed when the
server was shut down. This cased issues in some cases where this resulted in the inability to restart

the server, such as on flow update. Now, the sockets are properly closed on shutdown allowing the
server to be restarted.
• #5165: Previously, in the cases of importing of APIs or saving flows, that were coming from a swagger
with special symbols in the title, was failing due to our internal validations. Now, special symbols are
allowed.
• #5233: Previously, when plugins were loaded, in certain edge cases the whole service config was
passed to the plugin instead of the data in its own configuration section. Now, plugins will only receive
their own configuration. This is enabled with a feature flag. See deprecation #9.
• #5242: Added pre-release support for credential management. Oauth2 credentials will be kept
evergreen if possible and these credentials can be used in flows. This feature is flagged and should
not be used in production. For additional information, refer to API Builder Credentials.
• #5298: Previously, when creating an endpoint by importing a swagger document an error would occur
if the document had a path-level parameters definition. Now, this is correctly handled and will not
cause an error.
• #5307: Previously, APIs automatically generated from data connector models incorrectly specified
their response type for Query and FindAll. Now, they specify the correct response schema.
• #5308: Previously, when importing APIs from URLs in the Admin UI, the requests to retrieve the
swagger URL did not use the configured proxy settings. Now, the requests will use the proxy
configured in the API Builder configuration file.
• #5323: Previously, the documentation link in the flow editor was invalid and redirected to a non-
existent page. Now, the link redirects to the correct documentation.
• #5325: Previously, there was a spelling error in the description of the "Set Context" flow-node. Now, the
description is correctly spelled.
New Deprecations
• #9: Configuration change to enable receiving only the config relevant when uploading plugins
(enableScopedConfig). For information on how to be prepared for the change and to start using the
new behavior now, refer to Change in the way config is passed to plugins.
When upgrading to this release, you should consider the complete list of deprecated features.
Updated modules
Updated plugins

Known Issues
ENOTFOUND errors.
{
"swagger": "2.0",
"paths" {
"x-path": {
"get": {}
},
"/find": {
},
"/search": {
}
}
}
• #4280: Editing large object parameters on the API Orchestration page in the API Builder Console may
cause multiple, confusing flow-node configuration panel scrollbars to appear.
an ERR_INVALID_ARG_TYPE error rather than an "invalid npm package name".

• #4795: The MongoDB plugin @axway/api-builder-plugin-dc-mongo does not correctly support

primary keys that are not object identifiers. The MongoDB specification allows for primary keys of

by the flow.

API Builder Standalone - Halifax
Summary

• Features
• Fixes
• Release Notes
• Updated Modules
• Updated Plugins
• Known Issues
Features
• #4043: Add dropdown for string and number enum parameters in flows
• #5126: Left side menu should be expanded by default
Fixes
• #4810: JSONSelect CVE-2011-4969

• #4818: UI Incorrectly counts parameters definition as an endpoint in APIs list
Release Notes
• #4043: Previously, flow-node input parameters of type string and number described as enums would
require the values to be typed manually. Now, a dropdown selection is available to allow an easy
selection of allowed inputs.
• #4810: Previously, jsonselect@0.4.0 was used indirectly by @axway/api-builder-runtime

and had three CVEs against it: CVE-2011-4969 - XSS with location.hash, CVE-2012-6708 - Selector
interpreted as HTML, and CVE-2015-9251 - 3rd party CORS request may execute. Now, this module is
no longer a runtime dependency.
• #4818: Previously, the total number of the endpoints in the API Docs view in the UI was counted
incorrectly in the occasions where the parameters were attached to the root level of the endpoint in
the swagger definition. Now, the total number is calculated correctly.
• #5126: Previously, the side navigation menu was collapsed by default and it wasn't remembering the
user's preference. Now, the side navigation menu is expanded by default and it will remember the
user's last choice and be consistent.
Updated Modules
Updated Plugins
Known Issues
ENOTFOUND errors.

• #3960: API Builder has issues with recognizing a required consumes value if anything is appended to
it, for example multipart/form-data; charset=utf-8.
JSON $ref will yield a 404. API Builder will fail to locate the method since it only exists when the whole
Swagger document is dereferenced. An example of a Swagger document using $ref:
{
"swagger": "2.0",
"paths" {
"x-path": {
"get": {}
},
"/find": {
},
"/search": {
}
}
}
cause multiple, confusing flow-node configuration panel scroll bars to appear.
an ERR_INVALID_ARG_TYPE error rather than "invalid npm package name".
• #4736: Given a swagger with an extension, for example, on the path item object, the Swagger flow-
node plugin can fail to load the swagger file, resulting in an error:
Error loading plugin: @axway/api-builder-plugin-fn-swagger. Cannot convert

undefined or null to object
• #4750: Methods Upsert or FindAndModify are not present in APIs generated from a mongo/mysql
connector based model.
builder-plugin-dc-mongo) responds with a 404 rather than creating a new entry when upsert
parameter is true.
• #4752: The format of a distinct query's response depends on the type of the connector.

• #4759: Calling Update or FindAndModify on a Model that uses the composite connector and contains
required fields may fail and cause the server to terminate.
• #4795: The MongoDB plugin @axway/api-builder-plugin-dc-mongo does not correctly support primary
keys that are not object identifiers. The MongoDB specification allows for primary keys of other types.
As a result, trying to use the plugin will result in errors:

• #4813: If the endpoint swagger file in /endpoints contains special characters in its name, for example
[test].json, the endpoint is not rendered correctly in the UI.
by the flow.
• #4961: Having the '%' symbol in various file names can cause problems in the API Builder Console and
with direct linking. It is therefore advisable to avoid using '%' in API, Endpoint, Flow, Model, and

API Builder Standalone - Geneva
Summary
• Features
• Fixes
• Release Notes
• Updated Modules

• New Plugins
• Updated Plugins
• Known Issues
Features
• #5075: Remove Connectors page

• #5129: Change the page title on the Summary screen
• #5177: Support HTTP Proxy configuration on the swagger plugin
Fixes
• #5069: Add 401 response to swagger definition for endpoints which require auth
• #5103: Update flow validation to handle superfluous authorization parameters
• #5123: Improve flow editor side-panel UX for long names
Release Notes
• #5069: Previously, the swagger document built by API Builder declared only the available responses
for each endpoint and API. Now, API Builder adds 401 response by default for all endpoints and API
that are missing description for 401 response. Adding 401 responses is not done in case
APIKeyAuthType config parameter is set to none.
• #5075: The Connectors page has been removed. The page lacked clarity on what was being displayed
and served no function.
• #5103: Previously, flows with superfluous authorization parameters were not failing validation when
loaded. Now, they will fail to validate.
• #5123: Previously, the Flow Editor displayed the tools in square boxes which limits the amount of
space for the tool name. Now, the tools are displayed in rectangular boxes which have more room for
the text and the mouse over text now also contains the name of the tool.
• #5129: Previously, the title on the Summary page was the application name, which was inconsistent
with the rest of the API builder UI. Now, the available information on the Summary page contains the
correct title and the project information is displayed in a more clear and consistent way.
• #5177: A new optional configuration parameter called 'proxy' has been added. When specified, it must
be a string and must hold valid url of a proxy server. This url could be passed down to plugins that do
http/s communication so they can tunnel the traffic through that proxy server.
Updated Modules
New Plugins
• @axway/api-builder-plugin-dc-mssql

Updated Plugins
Known Issues
ENOTFOUND errors.
{
"swagger": "2.0",
"paths" {
"x-path": {
"get": {}
},
"/find": {
},
"/search": {
}
}
}
cause multiple, confusing flow-node configuration panel scroll bars to appear.
• #4528: Initializing new project with api-builder init 1234 will throw an
ERR_INVALID_ARG_TYPE error rather than "invalid npm package name".


builder-plugin-dc-mongo) responds with a 404 rather than creating a new entry when upsert
parameter is true.

• #4818: In *API Doc and Test* the endpoint count of an API may be greater than it should be if an
endpoint file defines common parameters which are misinterpreted as additional paths.
by the flow.

API Builder Standalone - Fuji

Summary
• Fixes
• Release Notes
• Updated Modules
• Updated Plugins
• Known Issues
Fixes
• #4050: Fix rendering issue with SVG flow-node icons when using Firefox
• #5064: Improve the description of feature flag warnings in the CLI
• #5070: Allow condition node to compare empty strings
• #5079: Display a response body in Test API when the status code of the response is non-2xx
• #5093: Display a response body in Test API when the response body is "falsy"
• #5096: Fix issue where flow editor would stop responding when applying changes
Release Notes
• #4050: Previously, when using Firefox, SVG flow-node icons in the flow editor may not be rendered or
could appear stretched. Now, Firefox will display these icons correctly.
• #5064: Modified verbiage of feature flag warnings in the CLI to make them more descriptive.
• #5070: Previously, API Builder would not allow you to use the condition node to compare against
empty strings. Now, the value of the source and value parameters can both be empty strings.
• #5079: Previously, When using Test API to try an endpoint and a non-2xx response code was returned,
the body and headers of the response would not be displayed. Now, The UI correctly displays the body
and headers.
• #5093: Previously, APIs executed via the Test API would not display a response when the body was a
falsy value such as 0 or false. Now, the response will be displayed for this type of value.
• #5096: Previously, applying flow changes multiple times would cause the flow editor to stop
responding. Now, changes to flows can be applied as many times as needed without issue.
Updated Modules
Updated Plugins

Known Issues
ENOTFOUND errors.
{
"swagger": "2.0",
"paths" {
"x-path": {
"get": {}
},
"/find": {
},
"/search": {
}
}
}
• #4528: Initializing new project with api-builder init 1234 will throw an
ERR_INVALID_ARG_TYPE error rather than "invalid npm package name".


builder-plugin-dc-mongo) responds with a 404 rather than creating a new entry when the

• #4818: In *API Doc and Test* the endpoint count of an API may be greater than it should be if an
endpoint file defines common parameters which are misinterpreted as additional paths.
by the flow.

API Builder Standalone - Eden

Summary
• Features
• Fixes
• Release Notes
• Updated Modules
• Updated Plugins
• Known Issues
Features
• #4467: Support queries on Memory models using $like comparison operator

• #4758: Support comparison operators on aliased fields in Composite models
Fixes
• #4870: Fix issue with duplicate path detection when paths differ by parameter name/case
• #5028: Ensure that validation errors are cleared after saving changes in the flow editor
Release Notes
• #4467: Previously, the Memory connector did not support the $like comparison operator and would
return an empty result set. Now, the Memory connector will support the correct $like behavior. This
is enabled with a feature flag. See deprecation #8.
• #4758: Previously, queries on Composite models that have aliased fields only had support for the
$like comparison operator. Now, Composite models support queries on aliased fields with the
$like, $eq, $ne, $lt, $lte, $gt, $gte, $in, and $nin comparison operators. This is enabled with a
feature flag. See deprecation #7.
• #4870: Previously, API Builder would not correctly detect duplicate paths in endpoints if they differed
by the case of the path parameters. Now, these duplicate paths are detected and reported on startup.
• #5028: Previously, fixing and saving an invalid flow would erroneously mark the fixed node as still
invalid. Now, fixing a flow will be rendered correctly.
New Deprecations
• #7: Configuration change to enable additional comparison operators in composite model queries
(enableAliasesInCompositeOperators). For information on how to be prepared for the change and to
start using the new behavior now, refer to Change in the handling of comparison operators on
Composite models.
• #8: Configuration change to enable the Memory connector to support $like in queries
(enableMemoryConnectorLike). For information on how to be prepared for the change and to start
using the new behavior now, refer to Change in the handling of Memory model queries using $like
comparison operator.

Updated Modules
Updated Plugins
Known Issues
ENOTFOUND errors.
{
"swagger": "2.0",
"paths" {
"x-path": {
"get": {}
},
"/find": {
},
"/search": {
}
}
}

• #4050: When rendering the flow editor, the API Builder Console may fail to render the Scalable Vector
Graphics (SVG) icons correctly in the Firefox browser. The render failure may result in blank icons
being displayed in the tool panel and in the flow diagram. This is due to a long-standing bug in Firefox
that fails to scale SVG graphics correctly. To fix, edit the SVG icon and add height and width. For
example: <svg ... height="80" width="80" />
• #4716: Given a data connector that generates models from a database, and is configured to auto-
generate the API for those models (modelAutogen is set to true), and there exists a table with no
primary key, then the API Builder will not able to handle the following methods: Update, Delete, Find By
ID, Find and Modify, and Upsert.

• #4795: The MongoDB plugin api-builder-plugin-dc-mongo does not correctly support primary keys that
are not object identifiers. The MongoDB specification allows for primary keys of other types. As a
result, trying to use the plugin will result in errors:


API Builder Standalone - Dublin

Summary
• Features
• Fixes
• Release Notes
• Updated Modules
• Updated Plugins
• Known Issues
Features
• #4967: Support Intercom in API Builder

• #5004: Swagger plugin is generating many config files after editing one
• #5008: Support for plugin load failure terminating server
Fixes
• #4976: Swagger: Generated swagger for services does not set "security"
• #4982: Versions of @axway/api-builder-plugin-dc-mysql prior to '2.2.0' are incompatible with API
Builder when the ùsePrimaryKey` feature flag is enabled
Release Notes
• #4967: Added Intercom to the API Builder Console UI.
• #4976: Previously, the /apidoc/swagger.json did not set the security requirements and generated
Swagger in a way that was not representative of the services security mechanisms. Now, the
generated Swagger document has a security requirement that ensures the security is correct.
• #4982: Previously, the usePrimaryKeyType feature flag was not compatible with versions of @axway/
api-builder-plugin-dc-mysql prior to 2.2.0. Now, when the feature flag is enabled API Builder is
compatible with these versions of the plugin.
• #5004: Previously, the config generation did not behave correctly and did not preserve the service
name during the creation of the service config if the initially generated config had its service name
manually changed, ending up in generating configs endlessly on system restart. Now, the generated
configs by the swagger plugin preserve the service name and stops once a config for the given service
is created.
• #5008: Previously, errors when loading plugins were ignored. Now, these errors will terminate the
service by default. This is enabled with a feature flag. See deprecation #6.
New Deprecations
• #6: Configuration change to enable the service to exit on plugin failure (exitOnPluginFailure). For more
information on how to be prepared for the change and to start using the new behavior now, refer
to Change in the loading of plugins when errors occur.

Updated Modules
Updated Plugins
Known Issues
ENOTFOUND errors.
{
"swagger": "2.0",
"paths" {
"x-path": {
"get": {}
},
"/find": {
},
"/search": {
}
}
}

primary key, then the API Builder will not be able to handle the following methods: Update, Delete, Find
By ID, Find and Modify, and Upsert.



API Builder Standalone - Canberra
Summary
• Features
• Fixes
• Release Notes

• Updated Modules
• Updated Plugins
• Known Issues
Features
• #4532: Support data connectors actual primary key type in API, models, and flows
• #4724: Support for Models based on tables that have no primary key.
Fixes
• #4791: Model flow-node distinct method's schema does not support the PK field
• #4834: UI not showing error pages when internal errors occur.
• #4855: Show better CLI error when using unsupported node version
• #4869: Config: apiPrefix is not validated for a required leading slash.
• #4916: Endpoints with names that require URI encoding can't be opened in the UI
• #4920: Improve the findAndModify Swagger documentation
Release Notes
• #4532: Previously, APIs and flows generated for models created by data connectors assumed IDs
were of type string. Now, the APIs and flows will use the primary key type for the IDs. This is enabled
with a feature flag. See deprecation #5.
• #4724: Previously, if a model was created for a table that had no primary key the auto-generated APIs
did not work. Now, the correct set of APIs will be generated and work as expected. This is enabled
with a feature flag. See deprecation #4.
• #4791: Previously, distinct method schema did not allow using of the primary key field. Now, the
primary key field is added to the schema and can be specified in distinct queries.
• #4834: Previously, errors in API Builder runtime or invalid views in the console would not render an
error page and may have caused errors in the browser. Now, a consumable error page is shown when
most errors occur.
• #4855: Previously, when running the API Builder CLI on an unsupported Node.js version, there would
be an unhelpful syntax error. Now, a useful error is output on install and when running a command
which tells the user which version of Node.js to use.
• #4869: Previously, setting value without leading slash to apiPrefix configuration parameter resulted in
active service with improperly bound paths. Now, validation has been added for the apiPrefix
parameter, if the leading slash is missing exceptions are thrown and the service loading is interrupted.
• #4916: Previously, if the endpoint filename contained a % symbol the API Builder Console could not
open the detail page for that endpoint. Now, the endpoint detail page will open as expected.
• #4920: Previously, the findAndModify method had a misleading description stated that only a single
object is found and modified. Now, it is corrected to denote that multiple objects could be found but
only the first one in the list gets modified.

New Deprecations
• #4: Configuration change to enable using models that are created without a primary key
(enableModelsWithNoPrimaryKey). For information on how to be prepared for the change and to start
using the new behavior now, refer to Removal of unsupported APIs on Models that do not have a
primary key.
• #5: Configuration change to enable using a model's primary key as its ID ( usePrimaryKeyType ). For
information on how to be prepared for the change and to start using the new behavior now, refer
to Removal of strings as default Model IDs.
Updated Modules
Updated Plugins
Known Issues
ENOTFOUND errors.
{
"swagger": "2.0",
"paths" {
"x-path": {
"get": {}
},
"/find": {
},
"/search": {
}

}
}
cause multiple, confusing flow-node configuration panel scroll-bars to appear.




API Builder Standalone - Boston
Summary
• Features
• Fixes
• Release Notes
• Updated Modules
• Updated Plugins
• Known Issues
Features
• #4748: Allow swagger scheme, host, and basePath to be editable via configuration
Fixes
• #4896: Swagger for autogenerated APIs belonging to connectors fails to download
Release Notes
• #4748: A new apidoc section has been added in the configuration allowing for the host, schemes,
and basePath of the swagger API documentation to be overridden so that API Builder can continue to
provide valid documentation when the service is behind a proxy or ingress. This new section also
gives control over where the documentation is hosted (apidoc.prefix) and if the documentation is
turned off (apidoc.disabled). These new values override admin.apiDocPrefix and
admin.disableAPIDoc and are provided instead of them for new projects. For more information on
how to configure this, see the project configuration documentation. See deprecations #2 and #3.
• #4748: Previously, the configuration option admin.disableAPIDoc kept the swagger API
documentation disabled, even in development mode - which was opposed by the config
documentation. Now, since the documentation is required for the admin console to function correctly
if the admin console is enabled and installed, the value of admin.disableAPIDoc will not be
acknowledged. This will not affect production installs.
• #4748: Previously, if the service had no apiPrefix configured, the swagger API documentation would
include an invalid (empty) basePath. Now, basePath will not be added to the swagger API
documentation if the service configuration results in an empty basePath.
• #4896: Previously, the Download Swagger button on the API details page may not work if the API
name contains characters that require URL encoding. Now, the Download Swagger works for all APIs.

New Deprecations
• #2: Change in the configuration option used to change where the Swagger API documentation is
hosted (admin.apiDocPrefix).
• #3: Change in the configuration option used to disable Swagger API documentation
(admin.disableAPIDoc).
Updated Modules
Updated Plugins
Known Issues
ENOTFOUND errors.
{
"swagger": "2.0",
"paths" {
"x-path": {
"get": {}
},
"/find": {
},
"/search": {

}
}
}
cause multiple, confusing flow-node configuration panel scroll-bars to appear.
generate the API for those models (modelAutogen is set to true), and there exists a table with a
primary key that is not an auto-incremented number and not named "id" (e.g. is a PK on username),
then the API generated will not properly handle the methods for Upsert or Update. In the UI, Upsert will
render an example body with the non-id PK (e.g. username) and id and will also fail 500 with various
error messages depending on content of the body, "You must provide a Model id and data Object, that
will be persisted", required body parameter: username missing", "You must provide a Model id and
data Object, that will be persisted". Update will fail with 500 error "invalid field: id".




API Builder Standalone V4 - Athens
Summary
• Fixes
• Known Issues
• Updated Modules
• Release Notes
• Plug-ins
Fixes
• RDPP-4722 : Update dependencies to improve application size

• RDPP-4727 : Correct row count for composite models based on the Oracle database connector
RDPP-4760 : Correct the default response handling of service connectors and Swagger plug-ins when
they are used in flows
• RDPP-4834 : Update the API Builder Standalone user interface to display error pages when internal
errors occur
• RDPP-4838 : Update the display endpoint IDs in the user interface breadcrumbs to use their friendly
names
• RDPP-4860 : Update Swagger plug-in to handle URI encoded JSON schema references in Swagger files
• RDPP-4867 : Correct an issue with the UI listing configuration files incorrectly
Known Issues
• RDPP-3825: Filtering the API Builder Console administrator access using IPv6 addresses may cause
ENOTFOUND errors.
• RDPP-3867: When attempting to create and save a flow for an imported Swagger endpoint that
contains a path or paths defined by references the save will fail.
• RDPP-3960: The API Builder Console does not recognize a required consumes value for form
parameters if it is appended and the endpoint load will fail. For example:
"consumes": [
"multipart/form-data; charset=utf-8"
],
The appended character set (charset=utf-8) will cause the endpoint load to fail.
• RDPP-3979: When deleting endpoints which contain references within paths, a Page Not Found (404)
error may be displayed in the API Builder Console. For example, a Swagger document with references
within paths may look similar to this:
{
"swagger": "2.0",

"paths" {
"x-path": {
"get": {}
},
"/find": {
},
"/search": {
}
}
}
The API Builder Console will fail to find GET /find since it is inside a $ref. If the API Builder Console
has modified the referenced $ref, it could cause unexpected behavior for other paths referencing #/
paths/x-path such as /search - deleting GET /find could unexpectedly delete GET /search too.
• RDPP-4050: When rendering the flow editor, the API Builder Console may fail to render the Scalable
Vector Graphics (SVG) icons correctly in the Firefox browser. The render failure may result in blank
icons being displayed in the tool panel and in the flow diagram. This is due to a long-standing bug in
Firefox that fails to scale SVG graphics correctly. To fix, edit the SVG icon and add height and width.
For example: <svg ... height="80" width="80" />
• RDPP-4280: Editing large object parameters on the API Orchestration page in the API Builder Console
may cause multiple, confusing flow-node configuration panel scrollbars to appear.
• RDPP-4445: If a Swagger definition uses the allOf parameter, the body generated in the method test
window is incorrect.
• RDPP-4532: Given a data connector that generates models from a database, and is configured to
auto-generate the API for those models (modelAutogen is set to true), and there exists a table with
a primary key that is not an auto-incremented number and not named "id" (for example, is a PK on
username), then the API generated will not properly handle the methods for Upsert or Update. In the
UI, Upsert will render an example body with the non-id PK (for example, username) and id and will
also fail 500 with various error messages depending on content of the body, "You must provide a
Model id and data Object, that will be persisted", required body parameter: username missing", "You
must provide a Model id and data Object, that will be persisted". Update will fail with 500 error "invalid
field: id". Given a table "geozip", postalCode (PK string), lat (string), lng (string), the generated
API methods disallows Create or Upsert.
• RDPP-4716: Given a MySQL data connector that generates models from a database, and is configured
to auto-generate the API for those models (modelAutogen is set to true), and there exists a table
with no primary key, then the API Builder will not be able to handle the following methods: Update,
Delete, Find By ID, Find and Modify, and Upsert.
• RDPP-4724: Given an Oracle data connector that generates models from a database, and is
configured to auto-generate the API for those models (modelAutogen is set to true), and there
exists a table with no primary key, then the API Builder will not be able to handle the following
methods: Update, Delete, Find By ID, Find and Modify, and Upsert.
• RDPP-4736: Given a Swagger with an extension, for example, on the paths object, the Swagger flow-
node plugin can fail to load the Swagger file, resulting in an error: "Error loading plugin: @axway/api-
builder-plugin-fn-swagger. Cannot convert undefined or null to object."
• RDPP-4748: API Builder will set the value of schemes in the API Builder Standalone service's Swagger
document to the scheme which was used to request the document. This may result in endpoints

which don't define a scheme being set with this global value instead; however, in most cases, it will be
correct. Currently, it is not possible to edit what is displayed in the schemes object.
• RDPP-4752: The format of a distinct query's response depends on the type of the connector.
• RDPP-4759: Calling Update or Find and Modify on a Model that uses the composite connector and
contains the required fields may fail and cause the server to terminate.
• RDPP-4795: The Mongo database connector does not work well with public keys (PKs) that are not
ObjectID.
• RDPP-4813: If the endpoint Swagger file in the /endpoints directory contains special characters in
its name, for example [test].json, the endpoint is not rendered correctly in the UI.
• RDPP-4865: The Swagger flow-node plugin strips characters from valid object definition names which
can result in schema ID collisions.
• RDPP-4865: The Swagger flow-node plugin does not handle valid object definition names with ~ or /
in their name and can result in an invalid schema references in swagger flow-nodes.
• RDPP-4891: When saving a configuration file in the API Builder Standalone UI, the editor will briefly
display the old version of the configuration while the server restarts. Any changes to the configuration
will be saved as intended.
• RDPP-4896: When using the API Builder Standalone UI to download the Swagger document for an API
which was auto-generated from a model, the download will fail.
Updated Modules
This release includes the following module updates:
Release Notes
• RDPP-4722 : Reduced the production install size of the default service by roughly 23%.
• RDPP-4727: Previously, when a count query was executed on a composite model that is being
sourced from an Oracle DB Model the reported result count will never exceed 10 irrespective of how
many actual rows there are. Now, the count result count matches the actual number of rows.
• RDPP-4760 : Previously, service connectors and flow-nodes generated with api-builder-plugin-
fn-swagger did not handle the cases where the swagger definition had a default response. Now,
service connectors and flow-nodes generated with api-builder-plugin-fn-swagger use the
proper response description even when a default description exists. For example, if the service returns
an HTTP 301 code and there is not a described response for the HTTP 301 code the default response
will be used if present in the Swagger document.
• RDPP-4834: Previously, errors in API Builder runtime or invalid views in the console would not render
an error page and may have caused browser errors. Now, a consumable error page is shown when
most errors occur.
• RDPP-4838: Previously, the API Builder Standalone user interface breadcrumbs did not display the
friendly endpoint name. Now, the user interface breadcrumbs display the friendly endpoint name.
• RDPP-4860 : Previously, api-builder-plugin-fn-swagger would throw "Error: Invalid reference
token" when attempting to handle URI encoded JSON schema references in Swagger files. Now,
invalid reference errors are not thrown.

• RDPP-4867: Previously, when listing files on the Configuration tab, some of them would disappear
from the list. Now, configuration files do not disappear.
Plug-ins
Plug-ins Updated
This release includes the following plug-in updates:
API Builder Tools 4.0.0 Release Note

API Builder 4.0.0 - 29 June 2018
Summary
API Builder V4.0 enables customers to install and run API Builder in containerized environments. Previously,
API Builder could only be installed in a cloud environment. For information on installing and getting started
with API Builder V4.0, refer to the API Builder Getting Started Guide. The API Builder 4.0.0 release includes
the following changes and new features to implement the ability to install API Builder on-premise. The
release also includes breaking changes, fixed issues, known issues, and security vulnerabilities.
• Upgrade
• Features
• Fixes
• Release Notes
• Known Issues
• Security Vulnerabilities
Upgrade
For more detailed instructors on how to migrate to API Builder 4.0.0, please follow the API Builder v3 to v4
Upgrade Guide.

Breaking Changes
• Node Handlers from API Builder v3 are no longer compatible with API Builder v4. Node Handlers are
now referred to as Flow-Nodes.
• API Builder no longer loads Node Handlers from the ./nodehandlers directory.
• Existing Node Handlers are renamed and installed as Flow-Node plugins. More information can be
found here.
• The Admin UI has been removed from the API Builder runtime and should be installed as an explicit
development dependency: npm install --save-dev @axway/api-builder-admin@^1.0.0
• The Appc CLI is no longer used to initialize, run or deploy API Builder v4 services. @axway/api-builder
is the new CLI which should be used to create new projects. appc run is no longer required, replaced
with directly starting your service with node app.js. npm install is now explicitly required before
API Builder can start in order to pull the required dependencies from NPM.
• The minimum required version of NodeJS is now 8.9.
• The prefix of Model Flow-Node IDs has changed from nodehandler://arrow-flow-invoke to
nodehandler://api-builder-flow-invoke.
• Previously, without logLevel defined in the configuration, the default level would be 'trace', now it is
'none'. New projects are generated with logLevel defined as 'debug'.
• Previously, API Builder used different API keys based on the environment in which the service was
running. These were accessible in default.js as apikey_development, apikey_production and
potentially apikey_preproduction. Now, a single value apikey is used instead. If the value still
needs to be changed per-environment this value should be configured using an environment variable
instead.
• Previously, a number of appc_ prefixed variables were available in API Builder Web, used for accessing
environment and platform-specific information such as the environment and host. Now, these
variables have been removed and should be accessed in an alternative way.
• The /arrowPing.json endpoint has been renamed to /apibuilderPing.json. (Note that this has been re-
added in the Barcelona release).
• Previously, configuring the API Builder port by setting it to 0 would let the service start on any available
port. Now, the feature has been removed and the configured port must be valid and available.
• Previously, in config, baseurl could include the port as well as the hostname. Now, it is more strict and
should not include the port.
• RDPP-4075: Previously, API Builder loaded Service Connectors from the ./serviceconnectors
directory. Now, they are no longer supported.
• RDPP-4390: Previously, API Builder loaded Data Connectors from the ./connectors folder of your
project or the ./node_modules/connectors folder. Now, API Builder loads Connectors as API
Builder plugins which should be installed as npm package dependencies and accessible from ./
node_modules.
• RDPP-4390: Data connectors from API Builder v3 are no longer compatible with API Builder v4. The
Appc CLI is no longer used to install connectors. For a list of available Data Connectors in API Builder
v4 and how to use them, refer to API Builder Connectors.
• RDPP-4225: Previously, it was possible to specify environment variables from the operating system
environment and apply them to the API Builder runtime (for example, ARROW_PORT). Now, it is no
longer possible to automatically use ARROW_* environment properties. Instead, the configurable
environment properties need to be explicitly included in the API Builder's configuration files (for

example, conf/default.js), and reference the environment variable by name (for

example, process.env.APP_PORT).
• RDPP-4225: Previously, it was possible to have multiple sets of configuration files, for example,
"development", "production", and so forth. Now, only two sets of configuration files are recognized:
"default" and "local" (for example, default.js, foo.default.js, local.js,
and foo.local.js), where the local config files are ignored by Git and NPM.
• RDPP-4348: Previously, API Builder would write aggregated transactional logs to ./logs. Now, API
Builder logs everything to the console and as a result, the logging in conf/default.js is no longer
used. The existing logging configuration will have no effect on the application and can be removed
safely.
• RDPP-4390: Previously, Data Connector configuration would use the connector name as the key; for
example, appc.mysql, and then list specific configuration properties for the connector, including an
optional alias. Now, the Data Connector configuration will use the user-configurable alias as a key; for
example, mysql. The property connector is now required and must be set to the package name of
the Data Connector being used.
mysql: {
connector: '@axway/api-builder-plugin-dc-mysql',
user: 'root',
password: 'root'
}
• RDPP-4577: Previously, the Swagger generated for model CRUD APIs accepted additional properties
in the request. This could lead to errors and unexpected behavior. Now, the APIs do not accept
additional properties and they precisely define their return type in the id field.
• RDPP-4781: Previously, the API Builder runtime was in a module called arrow and was referred to as
Arrow. Now, the API Builder runtime is in a module called @axway/api-builder-runtime and is
referred to as APIBuilder.
• RDPP-4781: Previously, the API Builder React engine was in a module named arrow-react-
engine. Now, the API Builder React engine is in a module called @axway/api-builder-react-
engine.
• RDPP-4152: Previously, the methods on the model flow-nodes outputted Arrow.Model objects to the
Flow context. Interacting with these in subsequent flow-nodes required a knowledge of the internal
workings of the Model object. Now, the model flow-nodes output plain data objects containing the
fields and values from the model method. This will only cause issues for flows that were expecting the
Model object rather than a data object.
• RDPP-4368: Previously, the distinct method on flow-nodes for connectors had parameters
for sel and unsel that were ignored. Now, these parameters are removed from the model flow-node.
• RDPP-4550: Previously, endpoints with query parameters accepted page and per_page as well
as skip and limit. The problem is that it wasn't clear how to effectively use these. To exacerbate
the issue, supplying both sets of parameters would yield unexpected result ranges.
Now, page and per_page parameters have been removed since their functionality is a subset of what
can be provided by the skip and limit parameters. In the backend, page and per_page are
computed via skip and limit so connectors that rely on them should continue to function.
• RDPP-4602: Previously, model fields with default values would get set in the model schema without
validation or interpretation. Now, the default values are validated to ensure that they are cast as the
correct type.

• RDPP-4712: Previously, models would auto-generated API with optional body parameters for
the Create, Upsert, Update, and Find and Modify methods. Now, body parameters are required.
• RDPP-4732: Previously, there was a serialization.exposePrimaryKeyAsId configuration
option that was intended to force the primary key of a model to always be called id. Now, this
configuration option has been removed and the model primary key field will always be exposed using
its actual column name.
Features
• RDPP-1243: Previously, flows had no inputs and would receive implicit runtime
parameters $.params, $.request, $.config, and $.env for use at runtime. Now, those
parameters are explicitly part of the flow definition.
• RDPP-1243: Previously, "Generate endpoints" from a model would generate Flows that had
implicit $.params, $.request, $.config, and $.env inputs for use at runtime. Now, the generated
Flows only use the explicit API endpoint parameters needed to execute the model function,
e.g. $.limit and $.where.
• RDPP-4045: Previously, the flow editor UI had a Save button that would save the current flow being
edited and then exit to the list of API methods. Now, the flow editor UI has an Apply button that allows
the flow to be saved, but stays in the flow editor and does not exit. The Cancel button has also been
renamed to Close. If the flow has no changes, then Close will just exit. If the flow has changed,
then Close will prompt to save or discard changes before exiting.
• RDPP-4346: Previously, projects created with the Axway Flow SDK had to synchronously export their
flow-node specifications which prevented the use of asynchronous APIs, such as network calls or
complex parsers, when generating the flow-node specifications. Now, API Builder allows the flow-node
projects to export a Promise which will resolve with the flow-node specification, allowing for
asynchronous loading of the flow-node specifications. Now, this is the default behavior in all new flow-
node projects.
• RDPP-4392: Previously, the appc.composite Connector was installed separately into your
application. Now, the Connector has been renamed to composite and is now included as part of API
Builder with no need to install it separately.
• RDPP-4524: Previously, when a Flow was invoked it would log the step-by-step execution with only the
Flow-Node's ID which was not very user-friendly. Now, Flow logging will include the user-provided
Flow-Node name alongside the ID. For example, Format String (mustache.1).
Fixes
• RDPP-4350: Previously, importing API endpoints into API Builder would incorrectly apply a Content-
Type to GET methods. Now, imported endpoints do not apply Content-Type to GET methods.
• RDPP-4350: Previously, API Builder would apply consumes, produces, tags, schemes,
and security properties on the service's Swagger document. This would unintentionally mean that
any endpoints without these properties defined per-path, would take these global values instead of
their intended value. Now, any endpoints which are imported with any of these properties will only
have them applied to that endpoint's methods, and API Builder will not apply any of these properties
globally which could change the meaning of the resulting Swagger document.
• RDPP-4355: Previously, HTTP method verbs in the API Documentation page for endpoints were lower-
case. Now, they are correctly displayed in upper-case.
• RDPP-4363: Previously, importing a Swagger document with an empty title would save the file
to endpoints/*.json. This is because the file name is derived from the title. Also, if a file already
existed with the desired name, an error would be thrown. Now, the imported file name or URL

basename will be used if the Swagger title is blank. Additionally, if the desired filename already exists,
then the imported filename will have an integer appended to it to ensure uniqueness.
• RDPP-4368: Previously, the model generated API for distinct had options for sel and unsel that
were ignored. Now, these options are not added to the API.
• RDPP-4531: Previously, query parameters in the Swagger generated from models were missing some
maximum, minimum, and default properties. These are used to set parameter defaults and to enforce
correct user input. For example, the page query parameter should be set to a minimum value of 1.
Now, these values are part of the generated query parameters.
• RDPP-4559: Previously, when running an API Builder project that began with the character "u" on
Microsoft Windows, the service would fail to start with a SyntaxError: Invalid Unicode
escape sequence. Now, these projects will start correctly.
• RDPP-4578: Previously, after importing a Swagger API, when trying to invoke an API method that
consumes a body, where the consumes parameter was not defined in the original Swagger document
(either on the method, or globally), API Builder would return "Request validation failed: Parameter
(body) failed schema validation". Now, API Builder applies a default consumes parameter
of application/json. The Swagger 2.0 specification does not explicitly handle this condition but
their own tooling applies application/json and it is a reasonable assumption that the method can
default to application/json when the body must validate against a JSON schema.
• RDPP-4732: Previously, the primary keys on models had to be named id. Now, API Builder supports
primary key columns with names other than id.
Known Issues
• RDPP-3825: Filtering the API Builder Console administrator access using IPv6 addresses may cause
ENOTFOUND errors.
• RDPP-3867: When attempting to create and save a flow for an imported Swagger endpoint that
contains a path or paths defined by references the save will fail.
• RDPP-3960: The API Builder Console does not recognize a required consumes value for form
parameters if it is appended and the endpoint load will fail. For example:
"consumes": [
"multipart/form-data; charset=utf-8"
],
The appended character set (charset=utf-8) will cause the endpoint load to fail.
• RDPP-3979: When deleting endpoints which contain references within paths, a Page Not Found (404)
error may be displayed in the API Builder Console. For example, a Swagger document with references
within paths may look similar to this:
{
"swagger": "2.0",
"paths" {
"x-path": {
"get": {}
},
"/find": {
},
"/search": {

}
}
The API Builder Console will fail to find GET /find since it is inside a $ref. If the API Builder Console
has modified the referenced $ref, it could cause unexpected behavior for other paths referencing #/
paths/x-path such as /search - deleting GET /find could unexpectedly delete GET /search too.
• RDPP-4050: When rendering the flow editor, the API Builder Console may fail to render the Scalable
Vector Graphics (SVG) icons correctly in the Firefox browser. The render failure may result in blank
icons being displayed in the tool panel and in the flow diagram. This is due to a long-standing bug in
Firefox that fails to scale SVG graphics correctly. To fix, edit the SVG icon and add height and width.
For example: <svg ... height="80" width="80" />
• RDPP-4280: Editing large object parameters on the API Orchestration page in the API Builder Console
may cause multiple, confusing flow-node configuration panel scrollbars to appear.
• RDPP-4445: If a Swagger definition uses the allOf parameter, the body generated in the method test
window is incorrect.
• RDPP-4532: Given a data connector that generates models from a database, and is configured to
auto-generate the API for those models (modelAutogen is set to true), and there exists a table with
a primary key that is not an auto-incremented number and not named "id" (for example, is a PK
on username), then the API generated will not properly handle the methods for Upsert or Update. In
the UI, Upsert will render an example body with the non-id PK (for example, username) and id and
will also fail 500 with various error messages depending on content of the body, "You must provide a
Model id and data Object, that will be persisted", required body parameter: username missing", "You
must provide a Model id and data Object, that will be persisted". Update will fail with 500 error "invalid
field: id". Given a table "geozip", postalCode (PK string), lat (string), lng (string), the generated
API methods disallows Create or Upsert.
• RDPP-4716: Given a MySQL data connector that generates models from a database, and is configured
to auto-generate the API for those models (modelAutogen is set to true), and there exists a table
with no primary key, then the API Builder will not be able to handle the following
• RDPP-4724: Given an Oracle data connector that generates models from a database, and is
configured to auto-generate the API for those models (modelAutogen is set to true), and there
exists a table with no primary key, then the API Builder will not be able to handle the following
• RDPP-4727: When executing a count query on a composite model that is being sourced from an
Oracle DB Model the reported result count will never exceed 10 irrespective of how many actual rows
there are.
• RDPP-4736: Given a Swagger with an extension, for example, on the paths object, the Swagger flow-
node plugin can fail to load the Swagger file, resulting in an error: "Error loading plugin: @axway/api-
builder-plugin-fn-swagger. Cannot convert undefined or null to object."
• RDPP-4748: The Swagger document describes the application's configured scheme, host, and port;
however, the application's scheme, host, and port are not editable via the application's configuration.
• RDPP-4752: The format of a distinct query's response depends on the type of the connector.
• RDPP-4759: Calling Update or Find and Modify on a Model that uses the composite connector and
contains the required fields may fail and cause the server to terminate.
• RDPP-4795: The Mongo database connector does not work well with public keys (PKs) that are not
ObjectID.

• RDPP-4813: If the endpoint Swagger file in the /endpoints directory contains special characters in
its name, for example [test].json, the endpoint is not rendered correctly in the UI.
Security Vulnerabilities
• RDPP-4810: JSONSelect
• Vulnerability: JSONSelect@0.4.0 is used indirectly by the api-builder-runtime. JSON path

is used in the flow engine and flow editor to query object value(s) at runtime. The issue identified
by the CVE is with a jQuery artifact that is vulnerable to XSS that is bundled with JSONSelect.
jQuery version 1.6.1 has the following relevant CVEs reported against it:
• CVE-2011-4969 - XSS with location.hash

• CVE-2012-6708 - Selector interpreted as HTML
• CVE-2015-9251 - 3rd party CORS request may execute
• Analysis: The JSONSelect npm package includes in its distribution, a copy of jQuery that is used
for unit-test and is not used by JSONSelect itself, and as a result, it is not a risk for API Builder.
• RDPP-4811: Bootstrap 20184
• Vulnerability: API Builder UI uses react-bootstrap which has a dependency on Bootstrap v3.3.7,
and it is 3.3.7 that contains the vulnerability. At the time of writing this ticket, Bootstrap did not
publish a 3.x version after 3.3.7, so no fix was ever released. The Bootstrap library is now at 4.x.
However, the react-bootstrap library that API Builder uses is actively working on a version
compatible with Bootstrap v4.x. The following issue is logged against Bootstrap v3.3.7:
• 20184 - XSS in data-target attribute

• Analysis: The vulnerability and risk are documented in 20184. The API Builder UI only runs on the
developer machine and is locked to localhost by default. The API Builder UI will not be installed
in production. Furthermore, the UI bundled with API Builder does not use data-target attributes.
The risk to API Builder is low.
Notable Connector Fixes
MySQL
• RDPP-4368: Previously, calling query on the MySQL connector with sel containing an unknown field
would have indeterminate results and would be potentially dangerous for SQL injection attacks. Now,
unknown fields are filtered out and will return an error.
• RDPP-4368: Previously, calling query on the MySQL connector with order containing unknown
columns would have indeterminate results and was open to SQL injection attacks. Now,
using order with an unknown column will return an error.
• RDPP-4368: Previously, calling distinct on the MySQL connector with an unknown field would have
indeterminate results and would be potentially dangerous for SQL injection attacks. Now, an unknown
field will return an error.
• RDPP-4368: Previously, calling query, distinct, count, or findAll on the MySQL connector with
a where option that contained unknown columns would have indeterminate results and was open to
SQL injection attacks. Now, using the where option with an unknown column will return an error.

• RDPP-4368: Previously, calling distinct or findAll on the MySQL connector would not honor
options for order, skip, or limit. Now, these options are honored.
• RDPP-4368: Previously, calling upsert on the MySQL connector with an un-escaped ID value would
have indeterminate results and would be potentially dangerous for SQL injection attacks. Now, ID is
passed as a placeholder and escaped.
• RDPP-4548: Previously, the MySQL connector did not support the decimal type. Now, support has
been added for decimal table fields and converts them to a number in the corresponding JavaScript
model.
Mongo
• RDPP-4700: Previously, the distinct method for Mongo database collections did not
honor skip, limit, or order query parameters. Now, the distinct method for Mongo database
collections honors skip, limit, or order query parameters.

API Builder FAQ
6
This document provides references to answer several API Builder frequently asked questions (FAQs).
How do I obtain support?

Contact the API Builder Axway Community to obtain support for API Builder.
How do I submit a bug?

Refer to Reporting Bugs or Requesting Features for more information.
Which versions of NPM and Node.js should I use?

You should have NPM (minimum 5.7), and Node.js (minimum 8.9) installed.
I get errors during npm install saying I need python installed!

This is not a bug with API Builder, and can safely be ignored. To bypass the error, you should run NPM
install as follows:
How do I setup API Builder CLI?

Refer to the Getting started section of API Builder Getting Started Guide for more information.
How do I create and run an API Builder project?

Refer to the Getting started section of API Builder Getting Started Guide for more information.
How do I configure access to the API Builder Admin console?

Refer to the Configuration section of API Builder Console for more information.
How do I create a model using the API Builder Admin console?

Refer to the Create a new model section of API Builder Getting Started Guide and the API Builder tabs
section of API Builder Console for more information.
How do I create API endpoints?

Refer to API Builder APIs for more information.
How do I configure API Builder?

Refer to Project Configuration for more information.
How do I create API Builder connectors?

Refer to API Builder Connectors for more information.

6 API Builder FAQ
How do I make a Docker container?

Refer to Dockerize an API Builder Service for more information.

API Builder Deprecations
7
API Builder regularly adds feature improvements, fixes, and occasionally identify and fix features that do not
work as designed, or are orthogonal to the intended direction of the product. When these are identified, we
mark them as deprecated and add them to this document. We intend to remove all the deprecated features
in the next major release of the product.
Warning: To ensure that you stay abreast of important updates and to make it easier to upgrade, you
should pay attention to the deprecation warnings and address them as soon as possible.
Direct or indirect use of deprecated features may result in a warning when the service starts. This should
not affect the functionality of your service, but the flags should be an indication that, if ignored, your service
may fall behind any future breaking changes and may increase the effort to upgrade to future major
releases.
Deprecation flags
Where fixing a bug or introducing a feature would introduce a breaking change, we create a deprecation flag
that is disabled by default, meaning that it will have no impact on your project. However, it should not be
ignored. These flags are provided to allow you to manually review the change and be aware of a functional
change that may also require code or config to be modified.
When addressing deprecation warnings with corresponding flags, you should compare the following set of
flags with those located in your ./conf/default.js. The full set of flags is below for convenience. In
upgraded applications, the flags are disabled by default. However, newly created applications will have
these flags enabled. For each deprecation warning, you should find the corresponding feature flag below,
read the document, and understand how it applies to your application. To ensure that your application
continues to operate as expected, it is essential that you have unit-tests for all your interfaces. Enabling a
flag, without understanding or testing the impact can have adverse effects.
./conf/default.js
module.exports = {
flags: {
// Flags to enable features that are not ready for production
or
// whose use may require manual upgrade steps in legacy
services.
// Enable support for aliases in comparison operators on
composite models.
// Breaking change for old versions as previously queries $lt,
$gt, $lte, $gte, $in, $nin,
// $eq would not have translated aliased fields.
enableAliasesInCompositeOperators: false,
// Enable support for the $like comparison operator in the
Memory connector.
enableMemoryConnectorLike: false,
// Enable support for Models that have no primary key.

7 API Builder Deprecations
// Breaking change for old versions as previously the Create

API returned a location
// header. Also the model advertised unsupported methods.
enableModelsWithNoPrimaryKey: false,
// Generate APIs and Flows that user primary key type rather
than always assuming string.
// Breaking change for old versions as the generated APIs will
change when enabled.
usePrimaryKeyType: false,
// Enabling this flag will cause the service to exit when
there is a problem loading a plugin
exitOnPluginFailure: false,
// Enabling this flag ensures that a plugin only receives the
config relevant to that plugin.
enableScopedConfig: false,
// Enable support for null fields coming from Models
enableNullModelFields: false,
RFC-3986 in auto-generated
// API. Breaking change for old versions as previously names
like "foo/bar" will now be
// encoded as "foo%2Fbar"
enableModelNameEncoding: false,
RFC-3986 in API Builder's
// Swagger. Breaking change for old versions as previously
names like "foo/bar" will now
// be encoded as "foo%2Fbar"
enableModelNameEncodingInSwagger: false,
// Enable support for model names being encoded whilst
preserving the connector's slash.
// This flag only applies when
enableModelNameEncodingInSwagger is enabled.
// Breaking change for old versions as previously model names
that start with a connector
// name, e.g. "oracle/foó" will now be encoded as "oracle/fo
%C3%B3".
enableModelNameEncodingWithConnectorSlash: false
}
};
List of Deprecated features

The following sections list the deprecated features.
[D001] /apidoc/docs.json
Beginning with the 4.0.0 release, Swagger API docs are available on /apidoc/swagger.json and are
mirrored on /apidoc/docs.json.
Using the /apidoc/docs.json endpoint to access Swagger API documentation is deprecated and /
apidoc/swagger.json should be used instead.

[D002] apiDocPrefix
Beginning with the Boston release, Usage of admin.apiDocPrefix in the project configuration has been
deprecated. Use apidoc.prefix instead. If both values are provided, apidoc.prefix will be preferred.
See Project Configuration.
[D003] disableAPIDoc
Beginning with the Boston release, Usage of admin.disableAPIDoc in the project configuration has been
deprecated. Use apidoc.disabled instead. If both values are provided, apidoc.disabled will be
preferred. See Project Configuration.
[D004] enableModelsWithNoPrimaryKey
Beginning with the Canberra release, For Models that do not have a primary key:
• The delete, findAndModify, findByID, upsert, and update APIs and endpoints will not be
generated.
• The Model flow-node will not have delete, findAndModify, findByID, upsert,
or update methods.
• The Create API will no longer return a location header.
This will be the default behavior in all new services. For more information on how to be prepared for the
change, and to start using the new behavior now, refer to Removal of unsupported APIs on Models that do
not have a primary key.
[D005] usePrimaryKeyType
Beginning with the Canberra release, Model IDs are based on the database's primary key type instead of
being hard-coded as a string.
change, and to start using the new behavior now, refer to Removal of strings as default Model IDs.
[D006] exitOnPluginFailure
Beginning with the Dublin release, Errors when loading API Builder plugins will cause the service to
terminate.
change, and to start using the new behavior now, refer to Change in the loading of plugins when errors
occur.
[D007] enableAliasesInCompositeOperators
Beginning with the Eden release, Queries on Composite Models will support comparison operators ($eq,
$ne, $in, $nin, $lt, $lte, $gt, $gte, $like) on aliased fields.
change, and to start using the new behavior now, refer to Change in the handling of comparison operators
on Composite models.

[D008] enableMemoryConnectorLike
Beginning with the Eden release, Queries on Models using the Memory connector that also use the $like
comparison operator will search using the query parameter instead of just returning an empty array.
change, and to start using the new behavior now, refer to Change in the handling of Memory model queries
using $like comparison operator.
[D009] enableScopedConfig
Beginning with the Istanbul release, When loading an API Builder plugin, you will only receive the config
relevant to the uploaded plugin.
change, and to start using the new behavior now, refer to Change in the way config is passed to plugins.
[D010] perURLAuthentication
Beginning with the Lisbon release, Authentication has changed to make all paths secure, and public paths
must be explicitly declared.
change, and to start using the new behavior now, refer to Change in the way of handling authentication and
authentication plugins.
[D011] API Builder Web
Beginning with the Lisbon release, API Builder Web is deprecated and will be removed in a future major
version. If you are currently using Web Routes, consider switching to another modern web application
architecture for your front end that consumes API Builder Service APIs.
[D012] enableModelNameEncoding
Beginning with the Osaka release, Model names are URI encoded as per RFC-3986, and the APIs that are
auto-generated for Models will bind to their URI equivalent.
change, and to start using the new behavior now, refer to Change in the way model name is encoded in URI.
[D013] enableNullModelFields
Beginning with the Quebec release, Queries on Models, which have fields with null values, can now return
that field in the response rather than hiding the field. Support for this behavior is dependent on the
connector being used.
change, and to start using the new behavior now, refer to Change in the way null fields are returned in
Models.
[D014] enableModelNameEncodingInSwagger
Beginning with the Quebec release, Model names are URI encoded as per RFC-3986, and the APIs that are
created from Generate endpoints for Models will bind to their URI equivalent.

change, and to start using the new behavior now, refer to Change in the way model name is encoded in
Swagger.
[D015] enableModelNameEncodingWithConnectorSlash
Beginning with the Barcelona release, Model names which are prefixed with their connector name (in other
words, oracle/user) will no longer have the slash encoded as %2F in auto-generated API paths.
This flag depends on [D012].
change, and to start using the new behavior now, refer to Change in the way model name with connector
prefix is encoded in paths.
[D016] Model.define
Beginning with the Cairo release, Model.define is deprecated and will be removed in a future version of
the product. Use Model.extend or APIBuilder.createModel instead.
[D017] Model instance reduce and APIBuilder.Model.reduce
Beginning with the Cairo release, Reducing a Model instance (i.e. Model.prototype.reduce) and
APIBuilder.Model.reduce are deprecated and will be removed in a future version of the product. For
more information on how to be prepared for the change, refer to Removal of the Model instance reduce and
APIBuilder.Model.reduce functions.
[D018] APIBuilder.removeModel
Beginning with the Cairo release, APIBuilder.removeModel is deprecated and will be removed in a
[D019] APIBuilder.removeConnector
Beginning with the Cairo release, APIBuilder.removeConnector is deprecated and will be removed in a
[D020] APIBuilder.removeBlock
Beginning with the Cairo release, APIBuilder.removeBlock is deprecated and will be removed in a
[D021] APIBuilder.removeAPI
Beginning with the Cairo release, APIBuilder.removeAPI is deprecated and will be removed in a future
version of the product.
[D022] APIBuilder.removeAPIByFilename
Beginning with the Cairo release, APIBuilder.removeAPIByFilename is deprecated and will be

[D023] APIBuilder.removeRoute
Beginning with the Cairo release, APIBuilder.removeRoute is deprecated and will be removed in a

[D024] Model prefix
Beginning with the Cairo release, Creating a Model with the prefix property is deprecated and will be
removed in a future version of the product. See Removal of Model prefix.
[D025] Model.prototype.extend
Beginning with the Cairo release, Extending a model instance (i.e. Model.prototype.extend) is
deprecated and will be removed in a future version of the product. Use Model.extend instead.
[D026] APIBuilder.app.locals
Beginning with the Cairo release, APIBuilder.app.locals properties appc_external_url,

appc_external_apidoc_path_legacy, appc_external_apidoc_path, or
appc_external_apidoc_url are deprecated and will be removed in a future version of the product.
[D027] APIBuilder.debug
Beginning with the Cairo release, APIBuilder.debug is deprecated and will be removed in a future
version of the product.
[D028] Codeblocks
Beginning with the Cairo release, Codeblocks are deprecated and will be removed in a future version of the
product. For more information on how to be prepared for the change, refer to Removal of Codeblocks.
[D029] @axway/api-builder-react-engine
Beginning with the Cairo release, @axway/api-builder-react-engine is deprecated and will not receive any
updates. If you are currently using Web Routes, consider switching to another modern web application
architecture for your front end that consumes API Builder Service APIs.
[D030] APIBuilder.get
Beginning with the Cairo release, APIBuilder.get is deprecated and will be removed in a future version
of the product.
[D031] APIBuilder.pluralize
Beginning with the Cairo release, APIBuilder.pluralize is deprecated and will be removed in a future
version of the product. Use the pluralize module instead.
[D032] APIBuilder.singularize
Beginning with the Cairo release, APIBuilder.singularize is deprecated and will be removed in a
future version of the product. Use the pluralize module instead.
[D033] APIBuilder.logger.stripColors
Beginning with the Cairo release, APIBuilder.logger.stripColors is deprecated and will be removed
in a future version of the product.
[D034] Model.fields[name].optional and API.parameters[name].optional
Beginning with the Cairo release, Using the optional property on Model fields and API parameters is
deprecated and will be ignored in a future version of the product. Use the required property instead.

[D035] Logger.createDefaultLogger
Beginning with the Cairo release, The static function Logger.createDefaultLogger is deprecated and
[D036] Logger.createRestifyLogger
Beginning with the Cairo release, The static function Logger.createRestifyLogger is deprecated and
[D037] Sort
Beginning with the Ennis release, Creating an API or Route with the sort property is deprecated in favor of
a more robust internal sort mechanism.
[D038] Port
Beginning with the Florence release, Usage of port in the project configuration has been deprecated. Use
http.port instead. See Project Configuration.
Change in the handling of Memory model queries

using $like comparison operator
This document describes deprecation [D008]
Change in the handling of Memory model queries using $like

comparison operator
Models using the Memory connector return an empty result set when attempting to perform a query that
uses the $like operator. For example:

This behavior has been deprecated since the API Builder Standalone - Eden release.
Beginning with the Eden release, queries on models that use the Memory connector will support the $like
comparison operator.

This will be the default behavior in all new services.
Why are we deprecating this feature
Previously, queries on Memory models that attempted to use the $like comparison operator would return
an empty result set. This could result in logic errors in your flows or APIs and is not the expected behavior of
the feature. It should return a result set that matches the query passed to it.
How does this impact my service
This is now the default behavior for all new services. Any existing services will continue to work as they
previously did, though it is strongly recommended you enable the new behavior on existing services.
The changed behavior only impacts services that query models which are using the Memory connector, and
those queries are using the $like operator.
Upgrading existing services
Updates contain important changes to improve the performance, stability, and security of your services.
Installing them ensures that your software continues to run safely and efficiently.

It is strongly recommended you upgrade API Builder to the latest version as well any data connectors you
may have in your stack. This feature requires a minimum of:
• API Builder Standalone - Eden
After upgrading, the enableMemoryConnectorLike feature will not be active until you enable it. To
enable it, add the following setting to your default.js file.
flags: {
enableMemoryConnectorLike: true
}
More default.js configuration file information can be found here: Project Configuration
Change in the handling of comparison operators on

Composite models
Change in the handling of comparison operators on Composite models

Composite models that use alias field names only have explicit support for the $like operator. Use of
other operators, such as $in, $nin, and so forth, with aliased fields, will behave the same as querying on a
non-existent field.
This behavior has been deprecated since API Builder Standalone - Eden release.
Beginning with the Eden release, queries on aliased fields in composite models will support the comparison
operators $eq, $ne, $in, $nin, $lt, $lte, $gt, $gte, and $like.
Previously, querying an aliased field could result in an unexpected result. For example, if a composite model
has an aliased field fname, the expectation is that a query such as
{"fname": { "$nin": ["Tom" ] } will return all the models except those with a fname of Tom.
However, the actual result is all rows, including those whose fname is Tom. This is due to the aliased field
being treated as a non-existent field.
Now, the aliased field is correctly mapped, and in the example scenario, only those rows whose fname is
not Tom will be returned.
The changed behavior may impact services that with queries on composite models that have aliased field
names.

• API Builder Standalone - Eden
After upgrading, the enableAliasesInCompositeOperators feature will not be active until you enable
it. To enable it, add the following setting to your default.js file.
flags: {
enableAliasesInCompositeOperators: true
}
Once enabled, review your service to ensure that you have no logic in your flows or APIs that depends on the
deprecated behavior.
Change in the loading of plugins when errors occur

Change in the loading of plugins when errors occur

When plugins fail to load correctly, the API Builder server would start, but log an error to the console, and the
functionality which the plugin provided would not be available.
This behavior has been deprecated since API Builder Standalone - Dublin release.
Beginning with the Dublin release, the API Builder server will fail to start when a plugin fails to load correctly.
When errors occur while loading a plugin, these errors are not always visible to the user. This could cause
confusion when a service does not behave as expected.
By causing the server to fail to start, this makes it clear to the user that something is wrong and needs to be
fixed before starting the service again.

The changed behavior may impact services that use incorrectly configured plugins.
• API Builder Standalone - Dublin
After upgrading, the exitOnPluginFailure feature will not be active until you enable it. To enable it, add
the following setting to your default.js file.
flags: {
exitOnPluginFailure: true
}
Change in the way config is passed to plugins

Change in the way config is passed to plugins

When plugins are loaded, the global config, which is irrelevant to what the plugin needs, may be passed to
the plugin's exported initialization function.
This behavior has been deprecated since API Builder Standalone - Istanbul release.
Beginning with the Istanbul release, an API Builder plugin will only receive its relevant config information.
This will be the default behavior for all new services.
Plugins should only receive configuration meant for their consumption as a parameter. Providing the whole
service configuration in the edge case described below was unintended. Since this change modifies the
interface to plugins, we are releasing it under a flag on an opt-in basis.
The following examples will show the previous behavior when the configuration is passed to the example
plugin api-builder-plugin-demo.

Previous behavior
If the pluginConfig key is not present in any configuration file loaded by the service, then the whole
config is passed to every plugin.
Service configuration
{
apiPrefix: '/foo',
proxy: 'example.proxy.com',
flags: {
enableScopedConfig: false
}
}
api-builder-plugin-demo
module.exports = (config) => {
console.log(config) // { apiPrefix: '/foo', proxy:
'example.proxy.com', flags: { enableScopedConfig: false } }
const flowNode = {}; // Define flow node
return Promise.resolve(flowNode);
};
If the pluginConfig key is present in a configuration file loaded by the service, or an additional key
matching the plugin name is provided, then the limited config is passed to every plugin.
{
apiPrefix: '/foo',
pluginConfig: {}, // or pluginConfig: { 'api-builder-plugin-demo':
{} },
flags: {
enableScopedConfig: false
}
}
console.log(config) // { proxy: 'example.proxy.com' }
};
New behavior (enableScopedConfig flag enabled)
If the pluginConfig key is not present in any configuration file loaded by the service, then the limited
config is passed to every plugin.
{
apiPrefix: '/foo',
flags: {
enableScopedConfig: true
}
}

console.log(config) // { proxy: 'example.proxy.com' }
};
This only affects services that rely on custom flow-node plugins, which in turn rely on a value only present in
the api-builder global configuration. This functionality was undocumented and unintended. API Builder
plugin developers should expect configuration to be provided under the namespace, which matches the
plugin name. If you are only using Axway provided plugins, this flag is safe to enable. Otherwise, check with
the plugin developer.
• API Builder Standalone - Istanbul
After upgrading, the enableScopedConfig feature will not be active until you enable it. To enable it, add
flags: {
enableScopedConfig: true
}
Change in the way model name is encoded in

Swagger
Change in the way model name is encoded in Swagger

Using model names as-is (without modification) when bound to ExpressJS API has been deprecated since
the API Builder Standalone - Quebec release.
Beginning in the Quebec release, model names will be percent-encoded according to RFC-3986 for
endpoints generated from Models, and for the Swagger that your application exposes (for example, on
http://localhost:8080/apidoc/swagger.json ).

Why we are making this change
Currently, model names are used to generate Swagger paths and schema without any encoding. According
to RFC-3986, characters not in A-Z a-z 0-9 - _ . ~, should be percent-encoded when included in a
URI. So, for example, currently, a model named "employee's" will produce an API path; for example /api/
endpoints/employee's/:id, which is not strictly correct. Many NodeJS libraries will automatically
encode requests to /api/endpoints/employee's, as /api/endpoints/employee%27s, which can
make calling the API difficult from NodeJS applications (API Builder will return 404 because it is not
listening on /api/endpoints/employee%27s). However, some HTTP clients, such as cURL, are less
strict and permit non-RFC-3986 URI. To make API Builder standards compliant and consistent with respect
to model names, when API Builder needs to encode model names into Swagger, they will be encoded as per
RFC-3986.
Generating new endpoints from a model will use the new RFC-3986 encoding. However, there is a potential
problem with existing endpoints that have been generated for models using (Models -> Generate endpoints)
can emit "Undefined schemas" errors on startup:
Startup Schema Error

Error loading endpoint at /home/user/app/endpoints/employees.json; Undefined
schemas:
schema:///model/employee's, schema:///model/employee's-full, schema:///model/
employee's,
schema:///model/employee's-full, schema:///model/employee's, schema:///model/
employee's-full,
schema:///model/employee's-full
Notice that the model "employee's" has an apostrophe and will encode as "employee%27s" using the
RFC-3986 encoding. The reason for the error is that the model is registered as a schema under "schema:///
model/employee%27s", but the endpoint file has a hard-coded schema references of "schema:///model/
employee's".
Most manually created model names are probably safe (in other words, it has only characters in A-Z a-z
0-9 - _ . ~). You can test your model names with the encodeURIComponentRFC3986 function below:
Encode URI Component RFC-3986

/**
* Encodes a URI component using a more strict RFC3986 encoding.
*
* @param {string} str - The string to encode.
* @return {string} The RFC3986 encoded component.
*/
function encodeURIComponentRFC3986(str) {
return encodeURIComponent(str).replace(/[!'()*]/g, function (c) {
return `%${c.charCodeAt(0).toString(16)}`;
});
}
If the function produces a different name, then your endpoints will be affected and will require a manual
upgrade. For example:
Example RFC-3986
console.log(encodeURIComponentRFC3986("employee's")); // "employee%27s"

Upgrading the existing configuration
• API Builder Standalone - Quebec
Enable the flag to encode model names in Swagger:
Enable model name URI encoding

flags: {
enableModelNameEncodingInSwagger: true
}
Then start your application. If it starts, then no further upgrade is required. However, if your application
emits an "Undefined schemas" error (above), you need to edit the affected endpoint file(s) to use the new
RFC-3986 encoding for your model name. For example, if your model name was "employee's", then all
references to "schema:///model/employee's" would need to be replaced with "schema:///model/employee
%27s". For example:

"200": {
"description": "The find all succeeded, and the results are available.",
"schema": {
"type": "array",
"items": {
"$ref": "schema:///model/employee's-full"
}
}
},
Replace all references of "schema:///model/employee's" with "schema:///model/employee%27s":

"200": {
"description": "The find all succeeded, and the results are available.",
"schema": {
"type": "array",
"items": {
"$ref": "schema:///model/employee%27s-full"
}
}
},
Note that you are only replacing the schema references. The word "employee's" is used in other places in
the file, and not just schema, so a search and replace should ensure that you search for the URI that
includes "schema:///model/".
You must search and replace files in endpoints and flows, for example, if your model is "employee's", then
edit these files:
• ./endpoints/employees.json

• ./flows/employees-create.json
• ./flows/employees-findAndModify.json
• ./flows/employees-update.json
• ./flows/employees-upsert.json
Once all endpoints have been updated, the upgrade is complete, and you can restart the server.
Change in the way model name is encoded in URI

Change in the way model name is encoded in URI

Using model names as-is (without modification) when bound to ExpressJS API has been deprecated since
the API Builder Standalone - Osaka release.
Beginning in the Osaka release, model names will be percent-encoded according to RFC-3986 for auto-
generated Model API.
Currently, model names are bound to auto-generated Model API paths for ExpressJS without any encoding.
According to RFC-3986, characters not in A-Z a-z 0-9 - _ . ~, should be percent-encoded when
included in a URI. So, for example, currently a model named "employee's" will be bound to an ExpressJS API
as /api/employee's. Many NodeJS libraries will automatically encode requests to /api/
employee's , as /api/employee%27s, which can make calling the API difficult from NodeJS
applications (API Builder will return 404 because it is not listening on /api/employee%27s). However,
some HTTP clients, such as cURL, are less strict and permit non-RFC-3986 URI. To make API Builder
standards compliant and consistent with respect to model names, when API Builder needs to encode model
names into a URI, they will be encoded as per RFC-3986.
Models that have auto-generated API can potentially have a different API, and clients that would previously
succeed in calling affected API will fail. This is especially true for models that are generated from the
database connectors. For example, "oracle/employee" will be bound to API /api/oracle%2Femployee.
Most manually created model names are probably generally safe. You can test your model names with the
encodeURIComponentRFC3986 function below:
Encode URI Component RFC-3986

/**
* Encodes a URI component using a more strict RFC3986 encoding.
*
* @param {string} str - The string to encode.
* @return {string} The RFC3986 encoded component.
*/
function encodeURIComponentRFC3986(str) {
return encodeURIComponent(str).replace(/[!'()*]/g, function (c) {
return `%${c.charCodeAt(0).toString(16)}`;
});
}

If the function produces a different name, then your model API will be affected. For example:
Example RFC-3986
console.log(encodeURIComponentRFC3986("oracle/employee")); // "oracle
%2Femployee"

flags: {
enableModelNameEncoding: true
}
After upgrading your configuration, you may also need to upgrade your clients to use the new API.
Change in the way model name with connector prefix

is encoded in paths
Change in the way model name with connector prefix is encoded in

paths
URL encoding a slash between the connector and model name has been deprecated since the API Builder
Standalone - Barcelona release.
Beginning in the Barcelona release, the slash separating the connector and model name will not be URL
encoded.
Models that originate from connectors generate an API that is unnecessarily encoding a slash. So, for
example, the Oracle connector might generate "oracle/user". If auto-generate API is enabled for the
connector, it will generate an API that looks like this: "/api/oracle%2Fuser/query". URL encoding the
slash that separates the connector name and the model name is unnecessary and ugly.
Model names which are prefixed with their connector name (for example, "oracle/user") will no longer
have the slash encoded as %2F in auto-generated API paths. In a
future release, these APIs will have a literal slash instead of %2F.
Any client that was previously accessing the Model auto-generated API using the percent-encoded slash
(for example, "/api/oracle%2Fuser/query") should now use a literal slash (for example, "/api/
oracle/user/query").

• API Builder Standalone - Barcelona
Enable the flag to encoded model name with connector slash:
This flag only applies when enableModelNameEncoding is enabled. Refer to Change in the way model name
is encoded in URI.
flags: {
enableModelNameEncodingWithConnectorSlash : true
}
After upgrading your configuration, you may also need to upgrade your clients to use the new API.
Change in the way null fields are returned in Models

Change in the way null fields are returned in Models

When retrieving data from Models, fields with null or undefined values would be missing from the response.
This behavior has been deprecated since API Builder Standalone - Quebec release.
Beginning with the Phoenix release, data retrieved from models will have null fields in the response.
Undefined fields will still not be returned. This behavior is part of the API Builder runtime but also relies on
the connector differentiating null values from undefined.
This will be the default behavior for all new services.
In the majority of cases, null is a valid data type in databases and should be represented in API Builder
rather than ignored. With SQL databases, users will expect consistent fields between records. For non-SQL
databases like MongoDB, fields may not be present or included records, and this should be differentiated
from existing fields that have null values.
The following examples will show the previous behavior when requesting data from a table where a field
can be null.
ID FIRST_NAME MIDDLE_NAME LAST_NAME
0 "Joe" NULL "Bloggs"
1 "Michael" "Daniel" "Higgins"
2 "Batman"

Previous behavior
Response
[
{
"ID": 0,
"FIRST_NAME": "Joe",
"LAST_NAME": "Bloggs"
},
{
"ID": 1,
"FIRST_NAME": "Michael",
"MIDDLE_NAME": "Daniel",
"LAST_NAME": "Higgins"
},
{
"ID": 2,
"FIRST_NAME": "Batman"
},
]
New behavior (enableNullModelFields flag enabled)
Response
[
{
"ID": 0,
"MIDDLE_NAME": null,
},
{
"ID": 1,
"FIRST_NAME": "Michael",
"MIDDLE_NAME": "Daniel",
"LAST_NAME": "Higgins"
},
{
"ID": 2,
"FIRST_NAME": "Batman"
},
]
Additional changes
This change alters the way that composite Models with multiple joins behave in certain situations. Given the
following two tables, and a composite join on both FIRST_NAME and MIDDLE_NAME, the requesting the
data would previously result in an unexpected response. The examples show the result of a findAll request,
which returns all fields which contain matching FIRST_NAME and MIDDLE_NAME fields. As you can see,
MIDDLE_NAME was previously ignored when the value was null, resulting in a second match with "Joe
James Bloggs".

ID FIRST_N MIDDLE_ LAST_NA ID FIRST_N MIDDLE_ LAST_NA

AME NAME ME AME NAME ME
0 "Joe" NULL "Bloggs" 0 "Joe" NULL "Bloggs"
1 "Michael" "Daniel" "Higgins" 1 "Joe" "James" "Bloggs"
Previous behavior
Response
[
{
},
{
}
]
New behavior (enableNullModelFields flag enabled)
Response
[
{
"MIDDLE_NAME": null,
}
]
This only affects services that rely on Models that have nullable fields.
• API Builder Standalone - Quebec
After upgrading, the enableNullModelFields feature will not be active until you enable it. To enable it, add the
following setting to your default.js file.
flags: {
enableNullModelFields: true
}

Change in the way of handling authentication and

authentication plugins
Change in the way of handling authentication and authentication

plugins
Configuration options for authentication and authentication plugins have changed, and have been moved to
a new accessControl configuration section. The moved APIKeyAuthType and APIKeyAuthPlugin
options have been deprecated alongside the custom matchURL authentication plugin method.
Beginning with the Lisbon release, authentication and authentication plugins have changed to ensure all
paths are secured by default. Authentication is applied to the API path (apiPrefix), and authentication is
controlled using a new configuration section, accessControl. All other paths are denied by default unless
they are made explicitly public by adding them to accessControl.paths. There are several public paths
added implicitly:
• /adminapi - this path is added if config.admin.enabled is true, and the application is installed in
development mode (for example, it is not production and api-builder-admin).
• /console - same as above.
• /apidoc - the config.apidoc.prefix path is added if config.apidoc.disabled is not true
(the default apidoc prefix is /apidoc).
Before the Lisbon release, authentication was using a URL path matching mechanism where each URL path
was tested first, and then credentials were tested separately. If a custom authentication plugin was used, it
would technically allow different security mechanisms to be applied to different paths. However, it was also
dangerous because it relied on the authentication plugins to match the URL correctly. If the URL matching
was not implemented correctly, there is a chance that the authentication could be bypassed, and routing
would continue. With this change, we are consolidating routing and authentication. The use of matchURL in
the authentication plugins does not fit into this security model, and so it has been deprecated.
From the Lisbon release, the chosen authentication scheme will always be applied to paths bound to the
apiPrefix. The type of authentication applied to these paths can be controlled in the configuration. API
Builder still supports matchURL for backward compatibility and the ability to apply security against
paths other than apiPrefix, but as already explained, this is not secure, so if your application
uses matchURL, it will emit a warning, for example:
matchURL warning
Deprecation: The configured authentication plugin is using using a deprecated
method 'matchURL' for applying security to paths and is potentially insecure.
Warning: Continuing to use the matchURL feature on custom authentication plugins is potentially insecure.

This fix explicitly forces a security check against all requests that match the apiPrefix. This means that
you are using a custom authentication plugin, and you previously did not require authentication
on /api/foo (in other words, matchURL would return false), then after this fix, your plugin will now be
forced to validate requests for /api/foo. While this is an edge-case, it is a breaking change, but a
necessary one for security purposes. If you wish to maintain this behavior, please see legacy
unauthenticated access below.
Additionally, except for a select few paths (mentioned above), access to all other paths will be denied by
default. To opt-out of this behavior, paths intended to be public must be explicitly declared within
the accessControl.public configuration.
These changes are compatible with the existing configuration. You should follow the upgrade guide to
update your service to comply with the latest security recommendations and features introduced in the
Lisbon release.
Continuing to use old configuration will emit a warning:
Old configuration warning

Deprecation: Config settings related to authentication have been deprecated
(APIKeyAuthType, and APIKeyAuthPlugin), use accessControl for API security
instead
Upgrading authentication: basic, apikey, or none
If using the standard authentication mechanisms: basic, apikey, or none, your existing configuration will look
similar to this:
Example configuration
apikey: 'kL51Ag9PtCR4xeTInjvhlolMlQqJ6FW3',
APIKeyAuthType: 'basic',
To upgrade, create a new key accessControl, and copy the value of APIKeyAuthType to
accessControl.apiPrefixSecurity. You should delete the key APIKeyAuthType. For example:
Upgraded configuration
accessControl: {
apiPrefixSecurity: 'basic',
public: []
}
Upgrading authentication: ldap
If using ldap, it will look similar to this:
APIKeyAuthType: 'ldap',
ldap: {
url: 'ldap://ldap.acme.io:1389',
adminDn: 'cn=read-only-admin,dc=example,dc=com',
adminPassword: 'password',
searchBase: 'dc=example,dc=com',

searchFilter: '(uid={{username}})',
reconnect: false,
connectTimeout: 2000
},
To upgrade, create a new key accessControl, and set the value

of accessControl.apiPrefixSecurity to 'ldap'. You should delete the key APIKeyAuthType. For
example:
accessControl: {
apiPrefixSecurity: 'ldap',
public: []
},
ldap: {
url: 'ldap://ldap.acme.io:1389',
adminDn: 'cn=read-only-admin,dc=example,dc=com',
adminPassword: 'password',
searchBase: 'dc=example,dc=com',
searchFilter: '(uid={{username}})',
reconnect: false,
connectTimeout: 2000
}
Upgrading custom authentication: plugin
If using a custom authentication plugin, your configuration will look similar to this:
APIKeyAuthType: 'plugin',
APIKeyAuthPlugin: 'custom-plugin.js'
To upgrade, create a new key accessControl, and set the value

of accessControl.apiPrefixSecurity to 'plugin'. Then, copy the value of APIKeyAuthPlugin to
accessControl.plugin. You should delete the keys APIKeyAuthType and APIKeyAuthPlugin.
accessControl: {
apiPrefixSecurity: 'plugin',
plugin: 'custom-plugin.js',
public: []
}
Your upgraded custom authentication plugin should not contain matchURL. For example:
Upgraded custom authentication plugin

function Plugin() {
}
Plugin.prototype.validateRequest = function (request, response, callback) {
// TODO: custom authentication
callback(null, true); // success!
};

Legacy unauthenticated access to paths having apiPrefix: plugin
We highly recommend that if you need unauthenticated paths, you use the public paths mechanism for
unauthenticated access. However, as stated above, if you implement a plugin where matchURL returned
false for paths residing on the apiPrefix (for example, /api by default) and wish to continue to provide
unauthenticated access those path(s), then you must implement this logic in validateRequest, and be
careful when testing the path. The code below does a case-insensitive test on the request.path.
Upgraded custom authentication plugin

function Plugin() {
}
Plugin.prototype.validateRequest = function (request, response, callback) {
if (request.path.toLowerCase().indexOf('/api/foo') === 0) {
// unauthenticated URL
return true;
}
// TODO: custom authentication
callback(null, true); // success!
};
Removal of Codeblocks
Removal of Codeblocks
The Codeblock was meant to be a way for users to create reusable JavaScript functions for Flows, akin to a
custom flow-node. However, it was always a difficult feature to use, could not be managed from the UI, and
over time API Builder added several features that allow users to make better use of JavaScript, such as the
axway-flow-sdk to build custom flow-nodes, and the @axway/api-builder-plugin-fn-javascript flow-node.
If you have a ./codeblocks directory, and it contains files (.js and .json), then your application is impacted
by this change.
Upgrading Codeblocks
You need to decide if you want to create a reusable flow-node using axway-flow-sdk, or if the code is
suitable for the JavaScript flow-node @axway/api-builder-plugin-fn-javascript. Follow the guides for
Creating a custom flow-node, or using the JavaScript flow-node. Once you migrate all of the Codeblocks
and adjust your Flows accordingly, then you can safely delete the ./codeblocks directory.
Removal of Model prefix


Removal of Model prefix

Beginning with the Cairo release, Creating a Model with the prefix property is deprecated and will be
If you need to host the autogenerated API for a Model on a path other than the configured apiPrefix, you
can use the prefix property to do so. This is not recommended for a number of reasons:
• The path provided is not relative to the configured apiPrefix and therefore, won't be described in the
Swagger for your service.
• The path provided may not have the configured auth strategy applied to it (since it's not relative to the
configured apiPrefix).
• The path will not be allowed access by default (will have to be added to the list of public paths in config
manually).
For these reasons, we will be deprecating this feature, and recommend using the default path for Model
autogenerated APIs.
Example of model using prefix

APIBuilder.Model.extend('user', {
prefix: '/myuser',
fields: {
name: {
type: 'string'
}
}
});
If you have any Models which have a prefix in their definition and you use their automatically generated
APIs, this will affect you after the next major release of API Builder. The prefix will no longer be used, and
the API will be available on the default path.
Removal of strings as default Model IDs

Primary keys will no longer default to string

Using strings as the default Model IDs in the generated APIs and flows has been deprecated since the API
Builder Standalone - Canberra release.
Beginning with the Canberra release, Model IDs are based on the database's primary key type. This will be
the default behavior in all new services.

Previously, APIs that required an ID always expected the Model ID to be a string, even if it was handled
internally as a numeric value. However, APIs that return IDs (for example, findAll) returned the ID using
the correct type. Now, to be consistent, all APIs will require and return the correct ID type.
How does this impact my application
The following areas are impacted:
• Flows
• Models
• API
Upgrading existing applications
• API Builder - Canberra

• Mongo data connector (@axway/api-builder-plugin-dc-mongo) version 1.1.0
• MySQL data connector (@axway/api-builder-plugin-dc-mysql) version 2.2.0
• Oracle data connector (@axway/api-builder-plugin-dc-oracle) version 2.2.0
After upgrading, the usePrimaryKeyType feature will not be enabled until you enable it. To enable it, add
flags: {
usePrimaryKeyType: true
}
Warning: Enabling the usePrimaryKeyType feature is a breaking change for old releases, and it is
recommended that you re-test your service after enabling the feature.
Removal of the Model instance reduce and

APIBuilder.Model.reduce functions

Removal of the Model instance reduce and APIBuilder.Model.reduce

functions
Beginning with the Cairo release, Reducing a Model instance (i.e. Model.prototype.reduce) and
APIBuilder.Model.reduce are deprecated and will be removed in a future version of the product.
The Model instance reduce and APIBuilder.Model.reduce functions were designed to achieve
three basic features:
1. Reduce (remove) fields from a parent model

2. Rename fields of a parent model
3. Add fields to a parent model
On review of these features, it was determined that all of these features could be achieved with
Model.extend, and because of that Model instance reduce and APIBuilder.Model.reduce
are redundant. For clarity and ease of use, these functions are deprecated.
The API Builder v3.x UI only uses Model.extend, so unless you manually code your Models, then this
change will not impact your service. However, if you manually create Models, you should check your
Models in the ./models directory to see if they use Model.reduce. If you are using Model.reduce, then
this feature will be removed in the next major version of the product, and you should migrate your models to
use Model.extend instead.
There are two ways to reduce a Model: one way is calling APIBuilder.Model.reduce.
Employee - APIBuilder.Model.reduce example

var Model = APIBuilder.Model.reduce('Friend', 'Person', {
"fields": {
"name": {
"type": "string"
}
},
"connector": "memory",
"actions": [
"create",
"read",
"update",
"delete",
"deleteAll"
]
});
module.exports = Model;
The other way is to call the reduce function on a Model instance (for example, Person.reduce).
Employee - Model.reduce example

var Model = APIBuilder.Model;
var Person = Model.getModel('Person');
var Model = Person.reduce('Friend', {

"fields": {
"name": {
"type": "string"
}
},
"connector": "memory",
"actions": [
"create",
"read",
"update",
"delete",
"deleteAll"
]
});
module.exports = Model;
If your application reduces Models in this way, then your application will be impacted by this change.
Upgrading models using the UI
The easiest way to upgrade a reduced model is with the UI. You will have to use a different model name
temporarily. In this example, the parent model is Employee, and your existing reduced model is Friend.
Select the menu on Person -> Compose into new.
This opens a dialog to generate a new composite model. We will give this model a different name, Friend2.

You now have an opportunity to edit the model. In this screen, you can remove or rename fields that are
sourced from the Person model. Make the changes to Friend2 so that it has equivalent fields to the Friend
model.
Click "Next >" to save and generate API for Friend2.
At this point, exit your application, delete the original model/Friend.js, and rename the new model/
Friend2.js file to model/Friend.js.
Finally, open the model/Friend.js file, and rename "Friend2" to "Friend" in APIBuilder.createModel.
Restart your application.
Removal of unsupported APIs on Models that do not

have a primary key
Removal of unsupported APIs on Models that do not have a primary key

Models based on the tables that do not have a primary key:
• Return an invalid location header in the Create API response calls.

• Generate APIs that have methods that rely on there being a primary key.
• Generate flow-nodes that have methods that rely on there being a primary key.
These have been deprecated since the API Builder Standalone - Canberra release.
Beginning with the Canberra release, for models that do not have a primary key:
• The delete, findAndModify, findByID, upsert, and update APIs and endpoints will not be
generated.
• The model flow-node will not have delete, findAndModify, findByID, upsert,
or update methods.
• The Create API will no longer return a location header.
The APIs generated for models that do not have primary keys are non-functional, and any attempt to use
them will result in errors. Also, the location header returned for the Create API was /api/<model>/
undefined which is incorrect, and any reliance on its value would likely result in errors.
The changed behavior only impacts services that use the MySQL or Oracle data connectors and are
connecting to databases that have tables that do not have primary keys. The following areas are impacted:
• Flows - Any flow using a model flow-node that does not have a primary key and is attempting to use
one of the removed methods will now be invalid.
• API - The auto-generated CRUD API for a model that does not have a primary key will no longer include
the delete, findAndModify, findByID, upsert, and update APIs. Previously, any call to these
APIs would have resulted in a response with the HTTP status code 500 (Server Error). Now, the
response will be an HTTP status code 404 (Not Found).
• Endpoints - Orchestrated APIs created using the "Generate endpoints" feature for models that do not
have a primary key will contain invalid endpoints for delete, findAndModify, findByID, upsert,
and update.
• API Builder - Canberra

• MySQL data connector (@axway/api-builder-plugin-dc-mysql) version 2.2.0
• Oracle data connector (@axway/api-builder-plugin-dc-oracle) version 2.2.0
Upgrading to the latest does not automatically enable the new behavior on pre-existing services. To enable
the behavior there, add the following setting to your default.js file.

flags: {
enableModelsWithNoPrimaryKey: true
}
Once enabled, start API Builder to check for invalid flows and endpoints. If there are any flows or endpoints
that are now invalid because of the removed methods, API Builder will fail to start with error messages. For
example, an Oracle model called NOPK would generate an error like:
1534267446154 Invalid flow oraclenopk-delete: {

"valid": false,
"errors": [
{
"type": "invalidMethod",
"code": "INVALID_VALUE",
"detail": {
"node": "model.delete",
"method": "delete"
}
}
]
}
The simplest solution, if there has been no customization to the orchestrated flows, is to delete the endpoint
and flows from the command line and then regenerate them using the "Generate endpoints" option on the
Models tab. In this example, those files would be:
• /flows/oraclenopk-*.json
• /endpoints/oraclenopk.json
If that is not an option, then the specifically deprecated methods can be removed. Remove the invalid flows
from the /flows folder of your project. For this example, they would be:
• /flows/oraclenopk-delete.json
• /flows/oraclenopk-findAndModify.json
• /flows/oraclenopk-findByID.json
• /flows/oraclenopk-update.json
• /flows/oraclenopk-upsert.json
Then open the endpoint file (for this example, /endpoints/oraclenopk.json) in a Swagger editor such
as https://stoplight.io/ or a text editor. Remove the following methods:
• /<modelname>/findaAndModify
• /<modelname>/upsert
• /<modelname>/{id}
Edit the response for the Create API, POST /<modelname>, and delete responses in the location header.
For /<modelname>/query and GET /<modelname> change the referenced schema and remove the -full
suffix. For example, change:

"200": {
"description": "The query succeeded, and the results are
available.",
"schema": {
"type": "array",
"items": {
"$ref": "schema:///model/oracle/NOPK-full"
}
}
}
Remove the -full suffix in the referenced schema.
"200": {
"description": "The query succeeded, and the results are
available.",
"schema": {
"type": "array",
"items": {
"$ref": "schema:///model/oracle/NOPK"
}
}
}
Once complete, your service should start; however, it is recommended that you re-test your service and
clients before deploying to production.

API Builder v3 to v4
Upgrade Guide 8
API Builder 3.x is deprecated
Support for API Builder 3.x will cease on 30 April 2020. Use the v3 to v4 upgrade guide to migrate all your
applications to API Builder 4.x.
Contact support@axway.com if you require migration assistance.
API Builder 4.0.0 introduced a large number of breaking changes. They are listed in detail alongside all the
other changes and fixes in the API Builder Tools 4.0.0 Release Note.
This guide covers the steps required for most users to migrate their projects from API Builder v3 to API
Builder v4.
Prerequisites
• NPM (minimum 5.7)
• Node.js (minimum 8.9)
• A local copy of your project, and that your project is backed-up or checked into source control.
Upgrade script
Once you have a local, backed-up copy of your project, you should run the upgrade script. The upgrade
script does a partial upgrade in situ, upgrading several dependencies in package.json as well as modifying
several files due to module renaming. Execute the following command within your v3 project directory:
Run API Builder upgrade script

$ npx @axway/api-builder-upgrade
Once the upgrade script completes, you should progress through each section in this document, and apply
any necessary changes to your project.
Admin UI
This upgrade is handled by the @axway/api-builder-upgrade script.
In v3, the admin UI was always installed as part of API Builder. While it was disabled in production, it added
a lot of unnecessary bulk to deployments. In v4, the admin UI is now a separate component, and if installed,
API Builder will load it. Upgraded projects should have "@axway/api-builder-admin": "^1.0.0" as a
devDependency.
To run the upgrade manually:
Install admin dev dependency

$ npm install --save-dev @axway/api-builder-admin@^1.0.0

8 API Builder v3 to v4 Upgrade Guide
Runtime
In v3, the API Builder runtime was named "arrow", and it was a dev-dependency by default, but may have
been added as a dependency in some cases.
package.json (v3)
"devDependencies": {
"arrow": "^*"
}
In v4, the "arrow" dev-dependency should be removed, and replaced a new API Builder runtime dependency,
"@axway/api-builder-runtime".
package.json (v4)
"dependencies": {
"@axway/api-builder-runtime": "^4.0.0"
}
In v3, all of your local *.js files (for example, APIs, blocks, models, and routes) require the "arrow" module.
models/testuser.js (v3)
var Arrow = require("arrow");
var User = Arrow.Model.extend('testuser', {
fields: {
},
connector: 'appc.arrowdb'
});
In v4, all of your local *.js should be modified to replace the require("arrow") with require("
@axway/api-builder-runtime").
models/testuser.js (v4)
var Arrow = require('@axway/api-builder-runtime');
var User = Arrow.Model.extend('testuser', {
fields: {
},
connector: 'appc.arrowdb'
});
Nodehandlers
In v3, there were several Flow Nodehandler dependencies that extended the Flow, and they were installed as
dependencies by default. In v4, Nodehandlers are now known as Flow-Nodes.

package.json (v3)
"dependencies": {
"nodehandler-base64": "^1.1.0",
"nodehandler-dot": "^1.1.0",
"nodehandler-json": "^1.1.0"
},
In v4, there are three nodehandlers that were renamed and repackaged as Flow-Node plugins (bas64, doT,
and json), and need to be renamed.
v3 v4
nodehandler-dot @axway/api-builder-plugin-fn-dot
nodehandler-base64 @axway/api-builder-plugin-fn-base64
nodehandler-json @axway/api-builder-plugin-fn-json
These should be added as plugins as npm dependencies.
package.json (v4)
"dependencies": {
"@axway/api-builder-plugin-fn-base64": "^2.0.0",
"@axway/api-builder-plugin-fn-dot": "^2.0.0",
"@axway/api-builder-plugin-fn-json": "^2.0.0"
},
In v3 flows have references to Nodehandlers.
flows/GreetFlow.json (v3)
"doT.1": {
"type": "nodehandler://nodehandler-dot/doT",
"name": "Format Greeting",
"method": "formatStr",
...
}
The v4 flows should have references to plugins.
flows/GreetFlow.json (v4)
"doT.1": {
"type": "nodehandler://@axway/api-builder-plugin-fn-dot/doT",
"name": "Format Greeting",
"method": "formatStr",
...
}
Warning: If you wrote your own nodehandlers in v3, they will not work in v4. If you have custom
nodehandlers that you wish to upgrade, contact support@axway.com.
Security issue

Note that doT has an npm security advisory against it (#798). Under normal use, the security issue does not
apply. However, the module is no longer actively maintained. If you do not use the GreetFlow and do not use
doT, then both can be removed. Remove the "nodehandler-dot" from package.json, and remove the example
Flow and API endpoint files.
Remove Greet flow example

$ rm flows/GreetFlow.json
$ rm endpoints/Greet.json
$ rm conf/greetflow.default.js
The @axway/api-builder-plugin-fn-dot plugin is no longer bundled with new API Builder projects. We suggest
using @axway/api-builder-plugin-fn-javascript instead of the formatObject method, or
@axway/api-builder-plugin-fn-mustache instead of formatString.
Model Node Handler distinct method

Previously, the distinct method on flow-nodes for connectors had parameters for sel and unsel that were
ignored. Now, these parameters are removed from the model Flow Node.
Model query pagination parameters 'page' and 'per_page'

Previously, the Model's query method supported pagination parameters page and per_page as well as
skip and limit. It was very unclear how to do pagination. Supplying both sets of parameters would yield
unexpected ranges. To simplify the Model query method and associated API
methods, page and per_page were removed.
Model.findAll
In v3, the programmatic API for Model.findAll was incorrect, returning a collection as the first element of an
array.
api.js (v3)
collection = myModel.FindAll()[0]
In v4, this was fixed to return a collection correctly.
api.js (v4)
collection = myModel.FindAll()
Connectors
Connector Name Comment
appc.arrowdb Renamed to @axway/api-builder-plugin-dc-mbs.

Note that this module has been redesigned and
released as a new data connector plugin to
the Mobile Backend Services. This new module
provides full support for custom objects. However,
it does not support the MBS built-in objects (for
example, acl, places, and so forth).
appc.composite Renamed to composite. This is now built into v4

and is no longer installed separately.

appc.mongo Renamed to @axway/api-builder-plugin-dc-mongo.
appc.mysql Renamed to @axway/api-builder-plugin-dc-mysql.
appc.mssql Renamed to @axway/api-builder-plugin-dc-mssql.
appc.oracle Renamed to @axway/api-builder-plugin-dc-oracle.
memory No change.
Other appc connectors
All other appc.* connectors are not supported in v4. If you need a connector upgraded, please contact
support@axway.com.
In v4, the connector dependencies are managed by npm, and no longer managed by appc. You can remove
the "dependencies" from appc.json.
appc.json
{
"type": "api",
"group": "arrow",
"dependencies": {
"connector/appc.arrowdb": "*",
"connector/appc.composite": "*"
},
"cloud": {
...
}
}
Configuration
The following sections describe the configuration changes from v3 to v4.
admin
Several admin configuration options have been removed, and a number have been deprecated. The
following are no longer required and can be safely removed from your
configuration: enableAdminInProduction, validEmails, validOrgs, prefix.
conf/default.js (v3)
admin: {
// control whether the admin website is available
enabled: true,
// the prefix for the API documentation
apiDocPrefix: '/apidoc',
// if you set disableAPIDoc, in production your swagger API docs will not
show up
disableAPIDoc: false,
'192.168.1.0/24', '10.1.1.1' ]


recommended due to security concerns.
allowedHosts: [
'localhost', '::1'
],
// set the email addresses you want to be able to log in to the admin
website
validEmails: [ 'support@axway.com' ],
// set the organization ids you want to be able to log in to the admin
website
validOrgs: [ 1234 ]
},
admin: {
// Control whether the admin website is available
enabled: true,
'192.168.1.0/24', '10.1.1.1' ]
recommended due to security concerns.
allowedHosts: [
'localhost', '::1'
]
},
apikey_*
API Builder no longer contains configuration per-environment. You should save-off the values
for apikey_development, apikey_production, and apikey_preproduction.
apikey_production: 'this-is-my-production-key',
// development key, this is the key that will be required when you are
testing non-production (such as locally)
apikey_development: 'this-is-my-development-key',
// preproduction key, this is the key that will be required when you are
testing non-production (such as locally)
apikey_preproduction: 'this-is-my-preproduction-key',
In v4, API Builder has one apikey configuration option. Changing values, such as apikey so that they are
different in different host environments, requires additional work. See the Environmentalization Guide for
more information.
In short, change apikey to be loaded from the environment.
apikey: process.env.API_KEY,
Add the value of the apikey_development key to a protected conf/.env:
conf/.env (v4)
API_KEY=this-is-my-development-key

You will need to provide the correct API_KEY credential for the specific runtime environment.
baseurl
The baseurl no longer supports port. Previously, it was possible to specify baseurl as 'http://
localhost:8080'. Now, baseurl is for the scheme and hostname only, and must not contain the port.
The baseurl configuration option is optional, and port is now a separate configuration option.
logging
In v3, API Builder would write files to a logging directory. The project's application and transaction logs
would be written to ./logs by default.
// logging configuration
logLevel: 'trace',
logging: {
// location of the logs if enabled
logdir: './logs',
// turn on transaction logs
transactionLogEnabled: true,
// turn on adi logging of transaction logs
adiLogging: false
},
In v4, API Builder no longer writes log files to a directory. All logs are emitted on the console stdout stream.
This makes it easier for services to integrate with platform logging aggregators. The logging configuration
can be deleted. Also, the default logLevel was changed to "debug".
// logging configuration
logLevel: 'debug',
You can delete the ./logs directory.
Delete unused ./logs

$ rm -rf ./logs
port
This is a new v4 option. However, it is critical if the service is to be successfully published to AMPLIFY
Runtime Services (ARS).
Also, you may also want to add this environment variable to a local environment .env file in the conf
directory.
conf/.env
PORT=8080
Note that you should always provide the PORT when deploying/running your service on a target
environment, for example when using Docker, or when publishing to ARS.
For more information, please read the Environmentalization guide.

serialization
Previously, there was a serialization.exposePrimaryKeyAsId configuration option that was

intended to force the primary key of a model always to be called id. Now, this configuration option has been
removed, and the model primary key field will always be exposed using its actual column name. The
configuration option serialization can be safely deleted.
serialization: {
// Here for backwards compatibility with older arrow apps. When you set
this to
// true, a model's primary key will always be exposed under 'id' instead
of it's
// actual name
exposePrimaryKeyAsId: false
}
Environment
In v3, the product supported any number of environments, such as "development" and "production".
Install admin dev dependency

$ ls -1 conf/
appc.arrowdb.development.js
appc.arrowdb.production.js
default.js
greetflow.default.js
While this was convenient, it is also potentially insecure as secure keys were stored in files by default, and
it's also contrary to https://12factor.net app best practices. API Builder v4 is designed to be a microservice
container that can run anywhere, not just https://www.axway.com/en/platform/runtime-services. In v4, API
Builder will only load ".*default.js" configuration files.
Generally speaking, you can follow the appc.arrowdb example below to environmentalize other
configuration parameters.
appc.arrowdb
If your API Builder v3 project uses ArrowDB, it will have two configuration files for "development" and
"production". To ensure your project upgrades correctly, you should environmentalize them.
appc.arrowdb.development.js (v3)
/**
* Generated ArrowDB configuration for development
*/
module.exports = {
"connectors": {
"appc.arrowdb": {
"enabled": true,
"connector": "appc.arrowdb",
"environment": "development",
"key": "MyArrowDBDevInstanceKey",
"baseurl": "https://api.cloud.appcelerator.com",
"username": "appc_app_user_dev",
"password": "dev-password",

generateModelsFromSchema: true,
modelAutogen:true
}
}
};
appc.arrowdb.production.js (v3)
/**
* Generated ArrowDB configuration for production
*/
module.exports = {
"connectors": {
"appc.arrowdb": {
"enabled": true,
"connector": "appc.arrowdb",
"environment": "development",
"key": "MyArrowDBProdInstanceKey",
"baseurl": "https://api.cloud.appcelerator.com",
"username": "appc_app_user",
"password": "prod-password"
}
}
};
Below is an example of how to upgrade ArrowDB configuration to v4 and at the same time, provide
environment variables. Note that in v4, "ArrowDB" was renamed to "MBS" or "Mobile Backend Services".
mbs.default.js (v4)
module.exports = {
connectors: {
'appc.arrowdb': {
enabled: true,
connector: '@axway/api-builder-plugin-dc-mbs',
baseurl: 'https://api.cloud.appcelerator.com',
key: process.env.MBS_KEY,
username: process.env.MBS_USERNAME,
password: process.env.MBS_PASSWORD
}
}
};
Then, add the environment variables to your conf/.env file for running your service in development. This
file should be secured, and only be read/writable by you, nor should it be checked into source control.
conf/.env
MBS_KEY=MyArrowDBDevInstanceKey
MBS_USERNAME=appc_app_user_dev
MBS_PASSWORD=dev-password
Note that this does not address your other environments, such as "production". Your project will have
production keys for ArrowDB, but how you address those environments is entirely up to you, but you should
address every environment that is necessary for your project. Generally speaking, they should be applied to
the target environment. So, you may add production environment values to your CI system, or you may
choose to create a script to set them. Whatever you choose, it should be secure and align with your CI/CD
process.

For more information, please read the Environmentalization guide.
ARROW_* environment variables
Previously, it was possible to specify environment variables from the operating system environment and
apply them to the API Builder runtime (for example, ARROW_PORT). Now, it is no longer possible to
automatically use ARROW_* environment properties. Instead, the configurable environment properties need
to be explicitly included in the API Builder's configuration files (for example, conf/default.js), and
reference the environment variable by name (for example, process.env.APP_PORT). See the
Environmentalization Guide for details.
Running your project

In v3, API Builder was installed and available globally as part of the Appcelerator CLI. You would run your
project using the appc run command.
Run API Builder (v3)

$ appc run
However, in v4, the runtime is now an explicit npm dependency (in other words, @axway/api-builder-
runtime). Your project is "standalone," and it is no longer necessary to install or log in to the Appc CLI to
run your project. In v4, you only use Node.js to run your project, so you should add a start script to your
package.json.
package.json (v4)
"scripts": {
"start": "node ."
}
If you applied the necessary upgrades listed above, and your project has all the necessary configuration and
environment necessary to run, then your project should start.
Run API Builder (v4)

$ npm start
Deprecation warnings
When you start your upgraded project, you may encounter several deprecation warnings. API Builder
releases every two weeks (see our past Release Notes), and each release follows an alphabetical naming
convention using cities. For example, the Akita release.
We regularly add feature improvements, fixes, and occasionally identify and fix features that do not work as
designed, or are orthogonal to the intended direction of the product. Where these would introduce a
breaking change, we create a deprecation flag that is disabled by default, meaning that it will have no
impact on your project. However, it should not be ignored. We intend to disable these features in the next
major release of the product. To stay abreast of the latest updates, and ensure that your project will
upgrade easily to the next major release, you should follow the API Builder Deprecations guide to upgrade
your project.
Warning: To ensure that you stay abreast of important updates and to make it easier to upgrade, you
should pay attention to the deprecation warnings and address them as soon as possible.

Deploying to AMPLIFY Runtime Services (ARS)

Once the major changes from this document are applied, and the necessary unit-tests are run to ensure your
project continues to work as expected, then you can follow this guide to Deploy an API Builder Standalone
application to AMPLIFY Runtime Services.

Api Builder Standalone 1-21-2020 PDF

Încărcat de

Informații document

Titlu original

Drepturi de autor

Formate disponibile

Partajați acest document

Partajați sau inserați document

Opțiuni de partajare

Vi se pare util acest document?

Este necorespunzător acest conținut?

Drepturi de autor:

Formate disponibile

Api Builder Standalone 1-21-2020 PDF

Încărcat de

Drepturi de autor:

Formate disponibile

API Builder Standalone

Saved as PDF January 21, 2020

2 API Builder Getting Started Guide..........................................................................................................................9

3 API Builder Developer Guide................................................................................................................................. 16

API Builder Standalone 3

API Builder Standalone 4

4 API Builder HOW TO..............................................................................................................................................231

5 API Builder Release Notes....................................................................................................................................328

API Builder Standalone 5

6 API Builder FAQ....................................................................................................................................................... 444

7 API Builder Deprecations..................................................................................................................................... 446

8 API Builder v3 to v4 Upgrade Guide..................................................................................................................479

API Builder Standalone 6

To get started, see the API Builder Getting Started Guide.

API Builder Standalone 7

• API Builder Getting Started Guide

API Builder Standalone 8

Install API Builder

Initialize a new project

Summary Your app's admin home page.

API Doc & Test Auto-generated documentation

Models Interface to help you build

API Builder Standalone 9

Configurations Lists configuration files that you

Credentials Lists the currently configured

Connectors Lists the components to extend

View Documentation Links to the Axway

Sidebar toggle Toggles the width of the sidebar.

Chat Click to make a suggestion or

The Admin Console is not deployed in Production installs of your application:

npm install --production --no-optional

Create a new model

1. Click the Models tab.

API Builder Standalone 10

3. In the New Model step:

a. Click the + Field button.

API Builder Standalone 11

b. Enter "first_name" in the Field name field (required).

c. Set Type to String.

API Builder Standalone 12

Access model data

API Builder Standalone 13

Providing environment-specific configuration

Example environmental configuration variables

Change port via env

API Builder Standalone 14

API Builder Standalone 15

• API Builder Console

API Builder Standalone 16

• API Builder Models

API Builder Console

API Builder Standalone 17

The admin dictionary can contain the following keys:

Key Type Default Description

allowedHosts Array<String> - Restrict access to the

enabled Boolean true Set to true to enable

API Builder tabs

API Builder Standalone 18

API Doc & Test

API Builder Standalone 19

1. Name your new model, select a connector, and add a description.

API Builder Standalone 20

See Project Configuration for an example and settings.