@axway/api-builder-sdk

A plugin SDK for implementing custom flow-nodes for API Builder.

Getting started

To get started with API Builder plugin development, use the @axway/amplify-api-builder-cli CLI to generate a new plugin project.

axway builder plugin init myplugin
cd api-builder-plugin-myplugin
npm test

That's it!

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.

Contributing

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 [email protected].

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

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

Install a plugin from a relative directory

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

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).

cd my-existing-api-builder-project
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

| 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 with a function called getPlugin. Edit this file if you wish to make use of some advanced features, like maintaining state. | | test/test.js | A mocha test suite. You should ensure all of your actions are adequately tested. |

Creating your own 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. You may first want to change the name, icon or description of the example flow-node.

flow-nodes:
  hello:
    name: Hello World
    icon: icon.svg
    description: Example flow-node to say hello.
    category: general

Then, you may want to change the method or change the method parameters, or JSON schema of the parameters, or the outputs. Finally, write your JavaScript in the action function.

JSON Schema

Flow-nodes utilize JSON Schema Draft-06 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 an array containing strings.
type: array
items:
  type: string

# The value must be an array containing numbers.
# Limits the number of items in the array to be between 1 and 10.
type: array
items:
  type: number
  minItems: 1
  maxItems: 10

Additional formats

Alongside the formats defined by the JSON schema specification, API Builder adds support for a number of additional formats which improve how the parameters are interacted with in the Flow editor.

# The value must be string and gets a multiline input editor.
type: string
format: multiline

# The value must be string and gets a JavaScript code editor.
# Supported from:
# @axway/[email protected]
# @axway/[email protected]
type: string
format: javascript

# The value must be string and gets a Mustache template editor.
# Supported from:
# @axway/[email protected]
# axway/[email protected]
type: string
format: mustache

# The value must be string and gets an XML editor.
# Supported from:
# @axway/[email protected]
# @axway/[email protected]
type: string
format: xml

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 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:
      # ...

flow-node attributes

The following table lists the attributes available when defining a flow-node:

| Keyword | Required | Description | | ------- | ----------- | -------- | | name | yes | A friendly name for your flow-node. This is how it will appear in the UI. Defaults to the flow-node key. | | icon | yes | 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 | yes | A summary of what the flow-node supports. | | category | yes | The category to which your flow-node should belong. | | methods | yes | 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.

| Keyword | Required | Description | | ------- | ----------- | -------- | | name | yes | A friendly name for your method. This is how it will appear in the UI. | | description | yes | A summary of the method. | | parameters | no | A set of unique parameter definitions. | | returns | see Description | Defines the value that is returned from your action method. If used, you must also use throws, and you cannot use outputs. You must use returns and throws or outputs. | | throws | see Description | Defines the Error that may be thrown from your action method. If used, you must also use returns, and you cannot use outputs. You must use returns and throws or outputs. | | outputs | see Description | A set of unique output definitions. If used, you cannot use returns and throws. You must use returns and throws or outputs. |

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 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.

• 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 (i.e. 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

| Keyword | Required | Description | | ------- | ----------- | -------- | | name | yes | The friendly name of the parameter. | | description | yes | A description of the parameter. | | required | yes | Specifies that the parameter is required. | | 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, "Authorization" is reserved for authorization parameters. | | 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. |

parameter multilineWrapper options

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 | yes | The leading text. The text should trail with a newline. | | after | yes | 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:

[
...
]

authorization parameters

The authorization parameters follow the same rules as regular parameters, save that an authorization parameter must be part of the "Authorization" group. The authorization parameter key is used when writing the flow-node action, so 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.

parameters:
  oauth2:
    description: oAuth2 authorization.
    group: Authorization
    required: true
    schema:
      type: object

authorization attributes

| Keyword | Required | Description | | ------- | ----------- | -------- | | description | yes | A description of the authorization. | | group | yes | The 'Authorization' group indicates this parameter is an authorization parameter. | | required | yes | Specifies that the authorization parameter is required. Defaults to true. | | schema | yes | A JSON schema that describes the acceptable value for the authorization parameter. |

returns

The returns key defines the successful output of the method's action function, for all possible value(s) that are returned from the function. This correlates to the "Next" output of the Flow editor. If using returns, you must also use throws.

returns:
  name: Next
  description: The operation was successful.
  context: $.hello
  schema:
    type: string

returns attributes

| Keyword | Required | Description | | ------------- | -------- | ------------------------------------------------------------ | | name | yes | A friendly name for the "Next" output of the flow-node. This is how it will appear in the Flow editor. | | description | yes | Describes the output value. | | context | no | A JSON path expression used to update the runtime context. For example, $.value. | | schema | no | A JSON schema that describes the output value. |

throws

The throws key defines the error output of the method's action function, for Error exceptions that are thrown from the function. This correlates to the "Error" output of the Flow editor. If using throws, you must also use returns.

throws:
  name: Error
  description: An unexpected error was encountered.
  context: $.error
  schema:
    type: string

throws attributes

| Keyword | Required | Description | | ------------- | -------- | ------------------------------------------------------------ | | name | yes | A friendly name for the "Error" output of the flow-node. This is how it will appear in the Flow editor. | | description | yes | Describes the output value. | | context | no | A JSON path expression used to update the runtime context. For example, $.value. | | schema | no | A JSON schema that describes the output value. |

outputs

The outputs key is an alternative way that the action method can be resolved, instead of using returns and throws. Each output can be thought of as an event that is triggered when the flow-node resolves at runtime.

However, using outputs should be discouraged because having multiple outputs complicates the flow-editor. We have plans to simplify the flow, and outputs are on our radar as usability issues. All possible return values can be sufficiently expressed using returns and throws, and we encourage you to do so.

Using 'outputs' attribute

Typically, successful outputs should be listed first, e.g. next, and error outputs should be listed last, e.g. error.

• Outputs are sorted by name in the Flow editor's 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 make use of Error objects in your error outputs.

outputs:
  next:
    name: Next
    description: Success
    context: $.value
  noResult:
    name: No Result
    description: No result found
    context: $.noResult
  error:
    name: Error
    description: Something happened
    context: $.error

To use the next output, you just return as normal.

async function getSomething(params, options) {
    return 'something';
}

To use the error output, you would throw an Error.

async function getSomething(params, options) {
    throw new Error('An error occurred.');
}

To use the noResult output, you would use the setOutput function that is passed through options, giving it the output key that you wish to invoke, and then return as normal.

async function getSomething(params, { setOutput }) {
    return setOutput('noResult', 'something');
}

output attributes

| Keyword | Required | Description | | ------------- | -------- | ------------------------------------------------------------ | | name | yes | A friendly name for the output of the flow-node. This is how it will appear in the Flow editor. | | description | yes | Describes the output value. | | context | no | A JSON path expression used to update the runtime context. For example, $.value. | | schema | no | A JSON schema that describes the output value. |

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.

async function getSomething(params, options) {
    # ...
}
module.exports = {
    getSomething
};

The first argument, params contains the all of input parameters that are necessary to invoke the action. If any input parameter fails to resolve, they will not be passed into the action method, even if they were required. It is up to the action method to enforce required parameters, or to choose defaults when they are not defined.

The flow-node input parameters, can be accessed using the same parameter key as was defined in the flow-node method (e.g. params.username).

• Actions are asynchronous and should return from the function with the value intended to be returned from the default output.
• 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(params, options) {
    if (params.username) {
        throw new Error('invalid username');
    }
    return { user: true };
}

The second argument, options contains additional data. options.logger provides access to the API Builder logging capabilities. It is used to log at the desired level (e.g. options.logger.error('...')).

options.pluginConfig is the user-configuration for this plugin that is loaded by the API Builder runtime in getPlugin. This is made available to the action method by passing an option of the same name to the SDK constructor: new SDK({ pluginConfig }).

options.pluginContext could be used to share context between actions. For example you could share context between all plugin actions and getPlugin - via the sdk.load(file, actions, { pluginContext }) . This is useful for storing any stateful information which may be required by all actions loaded from a file. Alternatively, you could set individual context on a per action basis by passing it in directly to the action(actions.hello, { pluginContext }) for those actions that really need it.

options.setOutput allows you to return from a custom output other than next. See below:

Returning from the action

Actions may return a value, or a Promise which resolves or rejects. Actions my also throw errors. Any thrown error will result in the error output being invoked in the flow, and returned values will invoke next.

If a flow-node does not define the next output, returning from the action will invoke the first defined output.

If a flow-node does not define the error output, throwing from the function will result in the flow terminating. This is why it is always recommended to include an error output in your flow-node.

Flow-nodes can have additional outputs, other than the conventional next and error, but this is discouraged. If additional outputs are required, then options.setOutput can be used to return using a non-conventional output.

setOutput

Triggers a custom output in the flow. Use this when you want to route to a non-conventional output other than next or error.

| Param | Type | Default | Description | | ----- | ---- | ------- | ----------- | | output | string | | The name of the output to trigger. Cannot be 'error'. | | value | * | | The value to resolve with. |

Returns: * - The value that was passed as a parameter.

Example

const value = encode(params.data);
return options.setOutput('encoded', value);

Maintaining state

Generally speaking, your flow-node actions should be stateless, and not rely on global state. It makes it much easier to write and test. However, there are times when a flow-node may need to depend on state. For example, if it maintains a connection. For that, you can create and set an external context by passing it into the options of sdk.load() to maintain state. Later, the context can be accessed from the options of your actions.

You can add a context in the getPlugin function in index.js. Note that if the getPlugin method throws an exception, then API Builder will exit. While you may think that you want that to happen, consider the users of your flow-node. If they install your plugin through the UI, and it requires some external configuration that have not been provided (e.g. credentials), then you will cause API Builder to exit, and that is not a good experience. Therefore, getPlugin should not throw exceptions.

Your flow-node actions have to deal with the state. For example, if the context maintains a connection, then your action methods need to test the state, and if disconnected, try to reconnect. If reconnect fails, then your action should fail (e.g. by throwing an Error). Let the flow designer that is using your flow-node decide on how deal with the connection issue (e.g. by sending an alert, or by returning a 500).

You should also handle restart in getPlugin. If your context depends on configuration, which can change between restarts, then you should reset the state so that you plugin uses the new configuration.

SDK.load(file, actions, options)

| Param | Type | Default | Description | | ------------- | ---- | ------- | ------------------------------------------------------------ | | file | string | | The absolute path to the JSON or YAML file. | | actions | Object | | An object where each key name corresponds to a method key defined in the specification. | | options | Object | | The plugin options. | | options.pluginContext | * | | The plugin context that will be passed to all actions passed to this load method. |

Example

// index.js
class Manager {
    connect(username, password) { }
    disconnect() { }
    isConnected() {}
}

async function getPlugin(pluginConfig, options) {
	const sdk = new SDK({ pluginConfig });
    // Store any configuration now because they will not be available
    // outside of this function.
    const manager = new Manager();
    try {
        manager.disconnect();
    } catch (ex) {
        // Handle this.  Do *not* throw exceptions from `getPlugin`.
        options.logger.error('Failed to disconnect', ex.stack);
    }
    try {
        manager.connect(pluginConfig.username, pluginConfig.password);
    } catch (ex) {
        // Handle this.  Do *not* throw exceptions from `getPlugin`.
        options.logger.error('Failed to connect', ex.stack);
    }
    const options = {
        pluginContext: manager
    };
    sdk.load(path.join(__dirname, 'flow-nodes.yml'), actions, options);
    return sdk.getPlugin();
}

// actions.js
async function hello(params, { logger, pluginConfig, pluginContext }) {
	const { name } = params;
    const manager = pluginContext;
    if (!manager.isConnected()) {
        // if this throws, then it will trigger the `error` output,
        // which allows the flow designer to handle the error.
        manager.connect(pluginConfig.username, pluginConfig.password);
    }
	return `Hello ${name}`;
}

Handling errors

It is important that you handle errors within your flow-node. If the error output is defined (see throws or outputs, then any exception that is thrown from your flow-node will result in the flow-node's error output being invoked. For example, if you throw an Error exception explicitly like this, then it will be caught and handled:

async function action(params, options) {
    throw new Error('An error occurred.');
}

If you do not define an error output (see throws or outputs), then exceptions thrown by your flow-node will abort the flow, however, API Builder service will continue to work as normal. Make sure you always define an error output so the flow designer can handle the error and flows are never aborted.

Promises

Another situation when you should be extra careful is when your action deals with Promises. If you run a flow with improperly handled Promise in your action unexpected results might happen. Assume we have the following function that represents third party code that rejects for some reason:

function doSomething () {
  return Promise.reject(new Error('boom'))
}

In the example bellow your API Builder service will get an UnhandledPromiseRejectionWarning. This may cause the API Builder server to exit in future node versions. The flow will also not wait for doStuff to complete. As a result the flow will not receive the returned 'data'.

async function action(params, options) {
  doSomething()
    .then(() => {
      return 'data';
    });
}

It's recommended to always have a catch handler at the end of any promise chain. In the next example, the promise is returned to API Builder, allowing it to wait for the promise to be fulfilled, and also handle any promise rejections. This ensures that this particular promise won't result in an UnhandledPromiseRejectionWarning if an error occurs.

async function action(params, options) {
  return doSomething()
    .then(() => {
      return 'data';
    });
}

If you need to handle promise rejections within your flow-node, for example if an error can be safely ignored or if you need to transform the error, then you can catch the error via catch handler. The promise should still be returned from the action. Ensure that you only throw Error objects from your flow-node for consistency. See the Summary of good practices.

async function action(params, options) {
  return doSomething()
    .then(() => {
      return 'data';
    })
    .catch((err) => {
       throw new Error(`transformed ${err.message}`);
    });
}

If processing the output of a promise is not required, you can directly return the promise, and let the SDK handle the result when the promise is fulfilled.

async function action(params, options) {
    return doSomething();
}

In cases where you need to wrap functions with callbacks make sure you always resolve/reject the Promise.

async function action(params, options) {
  return new Promise((resolve, reject) => {
    fs.copyFile('source.txt', 'destination.txt', (err) => {
      if (err) {
        return reject(err);
      } else {
        return resolve();
      }
    });
  });
}

Events

It's important to be particularly careful when you are working with events. For example, when working with streaming APIs, you must always ensure that you listen for the events that denote the completion of the processing. Otherwise the flow may end up waiting forever for a response from the flow-node, or unexpected behaviour may occur.

Here is specific example with fs.createReadStream. Note that the error event is handled and the possible exception during main processing is collected so the Promise completion is ensured.

const fs = require('fs');
function action(params, options) {
  return new Promise((resolve, reject) => {
    let error;
    let data = '';
    const readStream = fs.createReadStream('file.txt');

    readStream
     .on('error', err => {
      return reject(err);
     })
     .on('data', chunk => {
      try {
        // Aggregate your result here and do not resolve or reject
        // since this would be called multiple times
        data += chunk.toString();
      } catch(err) {
        // Wrapping in try/catch allows you to collect the error
        // in case it happen
        error = err;
        readStream.destroy(err);
      }
      })
      .on('end', () => {
        if (error) {
          return reject(error);
        } else {
          return resolve(data);
        }
      });
  }
}

Summary of good practices

• Always define the error output (or throws) on your flow-nodes.
• Always throw, reject or callback with Error objects rather than strings or other types of data.
• Be extra careful with async error handling - using the Promise .catch handlers or listening for error events.
• If you are managing state in your plugin make sure you clean it up properly in case of an exception.
• Test the error cases when you writing the test suite for your plugin.
• Read further information in this guide about error handling in Node.js.

Writing unit-tests

See @axway/api-builder-test-utils for the utilities and mocks needed for testing your flow-nodes.

If it's not already a devDependency in your package.json run the following command to ensure the utils are available for use during development and not shipped in your production code:

npm install --save-dev @axway/api-builder-test-utils

Debugging within API Builder

To debug a plugin from within a running API Builder service, 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(params, 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:

node --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.

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

Configuration

You can also install configuration file(s) for your plugin into the API Builder project directory by using @axway/api-builder-project-utils as part of a postinstall step.

As an example, if you wanted to distribute a sample configuration file, you would create a ".js" file in "./config". There are some rules for configuration files:

• The file must be valid javascript and have the ".default.js" extension;
• The file name must unique so that it cannot conflict with other configuration files;
• The file name should not be too long;
• The file must not crash API Builder on startup;
• The file should export pluginConfig and must use the plugin name (e.g. "api-builder-plugin-hello")

Create your configuration file:

// sample configuration for api-builder-plugin-hello
// conf/hello.default.js
module.exports = {
  pluginConfig: {
    'api-builder-plugin-hello': {
      key: 'value'
    }
  }
};

Manually install @axway/api-builder-project-utils as a dependency:

$ npm install @axway/api-builder-project-utils

Inside your package.json, create a "postinstall" script:

"postinstall": "api-builder-copy ./config/hello.default.js ./conf"

This instructs npm to execute a script after the module is installed, and it will install the file into the API Builder project ./conf directory.

Programmatic API

There is also an API that can be used to programmatically create flow-nodes. The interface can be found in docs/API.md.

Changes

2.0.2

• #7538: Removed @axway/flow devDependency.

2.0.1

• #7517: removed @axway/api-builder-test-utils devDependency again.

2.0.0

• #6089: Breaking change: requires minimum Node.js version 16.x.

1.2.6

• #7470: removed @axway/api-builder-test-utils devDependency.

1.2.5

• #7466: Update @axway/api-builder-test-utils devDependency.

1.2.4

• #7474: Internal dev-dependency move.

1.2.3

• #7376: Bumped @axway/flow dependency.

1.2.2

• #7434: Bumped @axway/flow dependency.

1.2.1

• #7287: Bumped @axway/api-builder-test-utils dependency.

1.2.0

• #6933: Replace peerDependency on @axway/api-builder-runtime with engines.apibuilder.

1.1.19

• #7242: Bumped axway-schema dependency.

1.1.18

• #7195: Bumped axway-schema dependency.

1.1.17

• #7206: Internal clean up.

1.1.16

• #7123: Bumped @axway/flow dependency.

1.1.15

• #7057: Update documentation links.

1.1.14

• #7066: Bumped @axway/api-builder-test-utils dependency.
• #6477: Internal code style changes.

1.1.13

• #7010: Bumped @axway/api-builder-test-utils dependency.

1.1.12

• #6999: Bumped @axway/api-builder-test-utils dependency.

1.1.11

• #6977: Added @axway/api-builder-uri-utils dependency.

1.1.10

• #6786: Bumped @axway/api-builder-test-utils dependency.

1.1.9

• #6835: Bumped @axway/flow dependency.

1.1.8

• #6919: Bumped @axway/flow dependency.

1.1.7

• #6826: Bumped @axway/flow dependency.

1.1.6

• #6877: Bumped @axway/flow dependency.

1.1.5

• #6833: Bumped @axway/flow dependency.

1.1.4

• #6865: Bumped @axway/flow dependency.

1.1.3

• #6775: Renamed amplify builder command references to axway builder.

1.1.2

• #6703: Bumped @axway/flow dependency.

1.1.1

• #5401: Bumped @axway/flow dependency.

1.1.0

• #6725: Added new parameter format: xml. This Flow editor feature is supported from @axway/[email protected].

1.0.9

• #6660: Bumped @axway/flow dependency.

1.0.8

• #6624: Bumped @axway/flow dependency.

1.0.7

• #6546: Bumped internal ajv dependency.

1.0.6

• #6534: Fixed documentation inconsistencies.

1.0.5

• #6522: Bumped devDependency @axway/flow to "6.6.0".

1.0.4

• #6463: Added Handling errors section to README.md.

1.0.3

• #6468: Bumped devDependency @axway/api-builder-test-utils to "1.1.0".

1.0.2

• #6338: Bumped devDependencies @axway/api-builder-test-utils to "1.0.0" and @axway/flow to "6.5.4".

1.0.1

• #4567: Added documentation for managing and installing configuration.

1.0.0

• #6441: No changes. First official release of @axway/api-builder-sdk.

0.10.0

• #6442: breaking change: Update params and options.authorizations to always be accessible as objects and never null when internal allowAuthClash option is true.

0.9.0

• #6437: Updated documentation.
• #6437: breaking change: Update SDK.add to throw an error if icon is not provided as an absolute path.
• #6437: breaking change: Update SDK.load to throw an error if file is not provided as an absolute path.

0.8.0

• #6337: breaking change: MockRuntime and MockLogger have been moved into @axway/api-builder-test-utils. To upgrade, add the new module as a devDependency and require it instead of @axway/api-builder-sdk within your unit tests.

0.7.1

• #6443: Updated internal scripts.

0.7.0

• #6237: breaking change: Added list of reserved identifiers which are not allowed to be used for methods. If any are used, an exception will be thrown.

0.6.2

• #6389: A new property, callback, has been added to the MockRuntime action result.

0.6.1

• #6428: Refactored MockRuntime action code.

0.6.0

• #6383: breaking change: The sdk.load(file, action) now performs schema validation against the contents of file.
• #6383: breaking change: In the YAML specification, flow-node name, icon, category, and description are now required properties. A flow-node must be specified in the YAML specification.
• #6383: breaking change: In the YAML specification, the method name, description, are now required properties. A flow-node must have at least one method.
• #6383: breaking change: In the YAML specification, methods must have outputs or returns and throws, but cannot have output with either returns or throws.
• #6383: breaking change: In the YAML specification, the parameter name, description, and required are now required properties.
• #6380: breaking change: The SDK's setContext() method has been removed. To set the pluginContext when loading flow-nodes, specify it as pluginContext in the third argument of sdk.load() (options),. When defining actions using action(), options is provided as the second argument.
• #6381: breaking change: .parameter(id, schema, options) no longer allows a boolean value as the third argument for setting the value required. required should instead be provided in the options object as the third argument.
• #6367: breaking change: The MockRuntime action result from invoking a method no longer contains args or context properties. Instead of result.args[1] the action response can be accessed from result.value.
• #6367: breaking change: when a flow-node action would result in the flow terminating (via throwing an error when there is no error output defined on the flow-node, or by calling an output callback with an error as the first argument outputs(error)), the MockRuntime action now throws the error instead of returning it in the result.
• #6379: breaking change: Added type checking when invoking methods through MockRuntime to ensure the arguments parameters and authorizations are passed as objects.
• #6368: The YAML specification now allows for methods to define returns and throws as an improvement over using outputs. However, outputs property is still available, but it cannot be used if using returns and throws.
• #6385: breaking change: The MockRuntime action will now throw an error if provided with parameters which aren't defined on the method.

0.5.0

• #6355: breaking change: Previously, authorization parameters were under the key authorizations in YAML, or defined using .authorization(). Now, Authorization parameters are included under the key parameters in YAML, or defined using parameter() and must be part of the Authorization group.
• #6355: breaking change: parameters and authorizations can no longer have the same key.
• #6355: breaking change: the action interface now groups parameters and authorizations under params. Previously, you would access parameters as req.params.paramName and authorization parameters as req.authorizations.authName. Now, you can access them directly through params - e.g params.paramName and params.authName.
• #6355: breaking change: outputs has been removed from the action interface. throw error; and return value; should be used instead to trigger the error or next outputs. If next is not defined, the default or first non-error output will be triggered instead. To invoke custom outputs, return options.setOutput('custom', value) should be used.
• #6355: breaking change: flow-nodes can now only specify a single default output.
• #6355: breaking change: flow-nodes must define a non-error output such as next.
• #6355: Added a feature to allow a custom pluginContext value to be shared between actions and getPlugin. This is set by calling sdk.setContext(pluginContext), and accessed in actions from options.pluginContext.
• #6355: Added allowAuthClash option to SDK constructor for internal use.

0.4.1

• #6316: Improved the MockRuntime interface for testing your flow-nodes and their methods. A plugin.getFlowNodeIds() method was added that returns the IDs of each flow-node within the plugin. Moreover, you can now get the names of all the available methods in a given flow-node with flownode.getMethods().

0.4.0

• #6312: breaking change: Removed SDK.clear API.
• #6312: Remove validation that limited the number of method action arguments to make the SDK more permissive.
• #6312: The SDK constructor takes an additional option pluginConfig: new SDK({ pluginConfig }).
• #6312: A pluginConfig property was added to action options. This is the same object as the pluginConfig option provided to the SDK constructor.

0.3.0

• #6329: breaking change: Simplified 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.
• #6329: breaking change: MockRuntime.validate moved to plugin.validate.
• #6329: breaking change: MockRuntime.getFlowNode moved to plugin.getFlowNode.
• #6329: An 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.
• #6329: A 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.
• #6313: Added the ability to provide authorization parameters to the mocked action methods via MockRuntime.

0.2.1

• #5012: Add authorization support to the API Builder SDK.

0.2.0

• #6238: Add support for async functions as actions.

0.1.2 - 0.1.4

• #6238: Adding a method will now automatically set empty description if unset.

0.1.1

• #6174: SDK documentation updates.

0.1.0

• #4899: breaking change: Renamed module from axway-flow-sdk to @axway/api-builder-sdk.
• #4899: breaking change: Removed axway-flow CLI and integrated it with @axway/api-builder CLI.
• #4899: breaking change: Removed mocknode and validate from axway-flow-sdk
• #4899: Added MockRuntime with mock and validate functions. Unit-testing flow-nodes must be done through MockRuntime.
• #4899: Added SDK.load function to simplify the generation of flow-nodes by referencing a static YAML or JSON file with the flow-node definition.
• #4899: breaking change: icon can no longer be provided to SDK.add as a relative path. Use path.join(__dirname, 'icon.svg') to dynamically get the absolute path to an icon in your plugin instead.
• #4899: breaking change: The plugin name and description are no longer generated from the module's package.json by default.

3.4.2

• #6116: Internal cleanup chore.

3.4.1

• #6074: Internal CI chore

3.4.0

• #5924: Added support for string parameters having a format of "mustache".

3.3.0

• #5892: Added support for defining a type for parameters to display by default in the Flow editor. Previously parameters always started with selector. Now they will consider the type provided using initialType as an option:

.parameter('myToggle', {
  type: 'boolean'
}, {
  initialType: 'boolean'
})

3.2.0

• #5891: Added alternative way to define parameter options. Instead of false as a third argument to .parameter(), an object can be provided as { required: false }.
• #5891: Added support for defining wrapper text for multiline and javascript format parameters. This wrapper text will be 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.

3.1.11

• #5923: Fix issue where README.md was not published.
• #5923: Fix issue where README.md was generated with hardcoded docs.

3.1.10

• #5914: Internal change to re-introduce readme generation from JSDoc.

3.1.9

• #5887: Fix issue where the axway-flow -n command would throw an error

3.1.8

• #5895: Fix issue where new Flow-Node projects would not get generated with a test directory.

3.1.7

• #5711: Internal cleanup of npm scripts.

3.1.6

• #5708: Internal changes removing readme autogeneration.

3.1.5

• #5708: Internal changes to mocha configuration.

3.1.4

• #5709: Internal changes to update eslint rules.

3.1.3

• #5707: Internal cleanup to code coverage during build process.

3.1.2

• #5742: Internal change to replace dot dependency with ejs when generating new flow-node plugins.

3.1.0

• #5600: Support schema references by disabling validation when building flow-nodes.

3.0.0

• #5436: Breaking Change: Minimum supported version of API Builder is now Jakarta
• #5436: Moves advanced HTTP options into a new group, "Advanced HTTP Options"

2.0.9

• #4757: Changed SCM repository and associated internal cleanup.

License

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.