@axway/api-builder-sdk
Advanced tools
A plugin SDK for implementing custom flow-nodes for API Builder flows.
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
You created your first API Builder plugin! The CLI generated an example flow-node called "Hello World" that creates greeting based on provided name. You can use this guide to modify it to create your own custom flow-node. To get you started you can have a look at our collection of examples.
You may be interested in contributing your own flow-nodes to the wider API Builder community. While you can choose to keep your flow-nodes private, there are a lot of benefits to making them freely available to the API Builder community as an open source initiative. If you do not want to "own" the source, you can contribute them to api-builder-extras. If you would like your component to appear in the Components list in the UI, we would be happy to review your component and add it to the list. You can email the API Builder team at API.Builder.Team@axway.com.
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):
Managing separate modules as dependencies requires a basic understanding of npm that is not covered by this guide (see this guide for more information).
In order 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
Assuming your projects all share the same root folder, you can install the plugin directly from source. Note that this is going to create a copy 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).
cd my-existing-api-builder-project
npm install ../api-builder-plugin-myplugin
npm start
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).
cd my-existing-api-builder-project
npm install ./api-builder-plugin-myplugin
npm start
├───package.json
├───src/
│ ├───actions.js
│ ├───flow-nodes.yml
│ ├───icon.svg
│ ├───index.js
└───test/
└───test.js
| File name | 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 src/flow-nodes.yml. You will add your own method implementations here. |
src/flow-nodes.yml | Defines your flow-node. You will modify to add your own 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. |
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:
To get started, you can modify the example generated by the CLI.
Flow-nodes utilize JSON schema to describe the acceptable values for various inputs and outputs. For simple parameters, this might just be one of the standard data types, e.g. 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
# The value must be an array containing strings.
type: array
items:
type: string
# The value must be an array containing numbers.
# Limits the minimum number of items of that array to at least 1 and the maximum to 10.
type: array
items:
type: number
minItems: 1
maxItems: 10
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 really just a container for a number of 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:
# ...
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 (e.g. 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. |
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.
name in the UI flow-node configuration panel.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:
# ...
The following table lists the attributes available when defining a method.
| Keyword | Required | Description |
|---|---|---|
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. |
authorizations | no | A set of unique authorization definitions. |
outputs | no | A set of unique output definitions. |
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 when writing the flow-node action. Typically, the parameter key should be simple property identifier (i.e. A-Z characters), otherwise it will be difficult to use it.
group), then alphabetically by parameter group.required: true), then alphabetically by parameter key.parameters:
username:
name: Username
description: The user name.
required: true
initialType: string
schema:
type: string
| Keyword | Required | Description |
|---|---|---|
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, e.g. "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 (e.g. 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. |
The multilineWrapper parameter option provides user-context in the UI when editing the parameter value. It gives context (e.g. 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:
| Keyword | Required | Description |
|---|---|---|
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:
[
...
]
An authorization defines authorization parameter to be used for the method's action function. The authorization is identified by a unique key below the method's authorizations attribute.
The authorization parameter key is used when writing the flow-node action. Typically, the authorization parameter key should be simple property identifier (i.e. A-Z characters), otherwise it will be difficult to use it. There is no limit to the number of authorizations that can be defined.
authorizations:
oauth2:
description: oAuth2 authorization.
required: true
schema:
type: object
| Keyword | Required | Description |
|---|---|---|
description | no | A description of the authorization. |
required | no | Specifies that the authorization is required. Defaults to true. |
schema | yes | A JSON schema that describes the acceptable value for the authorization. |
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, e.g. error.
name in the UI flow-node configuration panel.callback functions and are invoked from actions at runtime.callback function is stored in the context at runtime.Error in your error outputs.outputs:
next:
name: Next
description: Success
context: $.value
error:
name: Error
description: Something happened
context: $.error
The following table lists the attributes available when defining an output:
| Keyword | Required | Description |
|---|---|---|
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. |
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.
async function getSomething(req, outputs, options) {
# ...
}
module.exports = {
getSomething
};
The first argument, req is a runtime context from the flow engine. The flow engine resolves the all of 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 (e.g. req.param.username). In addition, the flow engine will also provide access to credentials via req.authorizations (see API Builder Credentials for more information).
outputs when the operation completes once.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.
The third argument, options is all the additional options provided from the flow engine. It provides access to the API Builder logging capabilities. It can be accessed via options.logger and used to log at the desired level(e.g. options.logger.error('...')).
options also provides pluginConfig which is the user-configuration for this plugin provided by the API Builder in getPlugin. This is made available to actions by passing an option of the same name to the SDK constructor: new SDK({ pluginConfig }). This is accessed within the action viaoptions.pluginConfig.
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 abruptly abort the flow. 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).
callback has an output function for every output defined for the method.callback must only be called once at runtime, and only after all asyncronous tasks are complete and the action is finished.The SDK comes a utility to help test your flow-node, MockRuntime.
const { MockRuntime } = require('@axway/api-builder-sdk');
Your plugin exports the getPlugin function in index.js. This will be required in your unit-tests.
const getPlugin = require('../src');
The plugin will be loaded and invoked by the API Builder runtime, so it is necessary to use MockRuntime to emulate this for unit-testing.
const plugin = await MockRuntime.loadPlugin(getPlugin);
The runtime instance has a validate function that ensures the flow-node adheres to the schema.
it('should define valid flownodes', () => {
// if this is invalid, it will throw and fail
plugin.validate();
});
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 = plugin.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 } });
});
In some cases, your flow-node may require credentials in addition to the standard parameters. The mocked action method has an additional argument that is used to provide authorized credentials:
it('should succeed with expected arguments', async () => {
const flowNode = runtime.getFlowNode('myplugin');
const params = { name: 'bob' };
const authorizations = { key: '1234' };
const result = await flowNode.getSomething(params, authorizations);
const expected = {
params: {
name: 'bob'
},
authorizations: {
key: '1234'
}
};
expect(result.callCount).to.equal(1);
expect(result.output).to.equal('next');
expect(result.args).to.deep.equal([ null, expected ]);
expect(result.context).to.deep.equal({ next: expected });
});
An async function that mocks the API Builder runtime that is used for testing flow-nodes. Pass it the getPlugin function from index.js. It resolves to a plugin that is suitable for testing.
const plugin = await MockRuntime.loadPlugin(getPlugin);
Validates the flow-nodes to ensure it adheres to the schema.
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 = plugin.getFlowNode('myplugin');
const result = await flowNode.getSomething({ username: 'jbloggs' });
The number of times the output callback was called.
An array of arguments that was passed into the callback function. The first argument is err and the second argument is the response value.
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.
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.
To debug the API Builder runtime, you can temporarily add a debugger statement (just 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 you 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 at your debugger statement.
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
There is also a API that can be used to programmatically generate flow-nodes.
SDK.clear API.action arguments to make the SDK more permissive.pluginConfig: new SDK({ pluginConfig }).pluginConfig property was added to action options. This is the same object as the pluginConfig option provided to the SDK constructor.MockRuntime interface for loading the plugin. Instead of calling getPlugin directly, a loadPlugin method was added to MockRuntime that calls getPlugin for you. Using this method, you can also pass plugin configuration and runtime options (e.g. logger) into your tests, e.g. await MockRuntime.loadPlugin(getPlugin, pluginConfig, options), which resolves to plugin.MockRuntime.validate moved to plugin.validate.MockRuntime.getFlowNode moved to plugin.getFlowNode.appDir property was added to getPlugin options, which is the API Builder's runtime project directory. When run in unit-tests, it is process.cwd but you can override this in MockRuntime.loadPlugin.logger property was added to getPlugin options and action options, which is the API Builder's runtime logger. When run in unit-tests, it is stubbed to not do any logging, but you can override this in MockRuntime.loadPlugin.MockRuntime.description if unset.axway-flow-sdk to @axway/api-builder-sdk@axway/api-builder CLImocknode and validate from axway-flow-sdkMockRuntime with mock and validate functionsMockRuntimeselector. Now they will consider the type provided using initialType as an option:.parameter('myToggle', {
type: 'boolean'
}, {
initialType: 'boolean'
})
false as a third argument to .parameter(), an object can be provided as { required: false }.axway-flow -n command would throw an errortest directory.dot dependency with ejs when generating new flow-node plugins.This code is proprietary, closed source software licensed to you by Axway. All Rights Reserved. You may not modify Axway’s code without express written permission of Axway. You are licensed to use and distribute your services developed with the use of this software and dependencies, including distributing reasonable and appropriate portions of the Axway code and dependencies. Except as set forth above, this code MUST not be copied or otherwise redistributed without express written permission of Axway. This module is licensed as part of the Axway Platform and governed under the terms of the Axway license agreement (General Conditions) located here: https://support.axway.com/en/auth/general-conditions; EXCEPT THAT IF YOU RECEIVED A FREE SUBSCRIPTION, LICENSE, OR SUPPORT SUBSCRIPTION FOR THIS CODE, NOTWITHSTANDING THE LANGUAGE OF THE GENERAL CONDITIONS, AXWAY HEREBY DISCLAIMS ALL SUPPORT AND MAINTENANCE OBLIGATIONS, AS WELL AS ALL EXPRESS AND IMPLIED WARRANTIES, INCLUDING BUT NOT LIMITED TO IMPLIED INFRINGEMENT WARRANTIES, WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE, AND YOU ACCEPT THE PRODUCT AS-IS AND WITH ALL FAULTS, SOLELY AT YOUR OWN RISK. Your right to use this software is strictly limited to the term (if any) of the license or subscription originally granted to you.
FAQs
SDK for implementing custom plugins for API Builder
The npm package @axway/api-builder-sdk receives a total of 288 weekly downloads. As such, @axway/api-builder-sdk popularity was classified as not popular.
We found that @axway/api-builder-sdk demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 15 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket researchers uncovered a malicious PyPI package exploiting Deezer’s API to enable coordinated music piracy through API abuse and C2 server control.
Research
The Socket Research Team discovered a malicious npm package, '@ton-wallet/create', stealing cryptocurrency wallet keys from developers and users in the TON ecosystem.
Security News
Newly introduced telemetry in devenv 1.4 sparked a backlash over privacy concerns, leading to the removal of its AI-powered feature after strong community pushback.