API Builder Getting Started Guide

Prerequisites

You should have NPM (recommended minimum v6.14.13), and Node.js (recommended minimum v14.17.0 LTS) installed.

API Builder v4 maintains compatibility with a minimum of Node.js v8.9, however, using a version older than v14.17.0 is not recommended. See the Node.js support policy for more information.

Minimum requirements

These are the absolute minimum requirements for running an API Builder service. Memory and disk usage may fluctuate over time and between releases. Recommended system specs should be significantly higher to account for additional plugins, inbound requests and custom service logic. 

Getting started

This section describes installing the Axway command line interface (CLI) and the API Builder CLI. The API Builder CLI is installed using the Axway CLI. We first describe how to install the Axway CLI, and then the API Builder CLI.

Install the Axway CLI globally

Refer to the Axway CLI documentation for more details.

npm install -g axway

Verify the Axway CLI installation by running the following command.

axway pm list

If you run into issues getting the Axway CLI working, see the Axway CLI troubleshooting guide. You may need to check that NPM and Node.js were installed correctly.

Install the API Builder CLI

The API Builder CLI is used to create new API Builder projects and plugins. 

Refer to API Builder CLI documentation for more details.

axway pm install @axway/amplify-api-builder-cli

Create a new API Builder project

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 a project called myproject in the ./myproject directory.

axway builder init myproject

Then, start the API Builder project.

cd myproject
npm start

Using version control

We recommend using version control for tracking changes. One popular version control solution is git. API Builder projects come with a .gitignore file which is used to ignore files and folders that should be downloaded or created as part of an install or build. These files and folders should not be versioned or distributed when sharing a project, as they can sometimes include sensitive information, or take up a large file size compared to the rest of the project (for example 150MB vs 30kb).

When cloning a project from elsewhere, you should ensure that all project dependencies, including API Builder itself, are installed before you can start the service. From the project directory run:

npm ci

If you have issues running this command, it may be because the project is missing a package-lock.json file which specifies an exact dependency tree for reproducible installs. If this is the case, then run npm install instead.

Updating API Builder

New versions of API Builder are released every 2 weeks, often containing important fixes and features. Each API Builder project depends on it's own version of API Builder which allows you to update your services individually.

To update API Builder run the following command from your project directory. This will also update any additional dependencies in your project.

npm update

If you're going to be creating more API Builder projects, it's important to use the latest API Builder CLI so that your new projects use the latest template.

npm install -g axway
axway pm update

For more information about fixes and features in new versions, see API Builder Release Notes. From time to time there will be changes to new projects and plugins. To keep your service in sync with these changes, see API Builder Updates. 

Introduction to the UI

Once your project is running, point your browser to http://localhost:8080/console to access the API Builder user interface (UI) console.

Upon reviewing the API Builder console, you can navigate to the following items.

	Summary	Your application's admin home page.
	API Doc & Test	Auto-generated documentation about your API endpoints. Provides help for the client application to access your application.
	Flows	Lists flows that are part of your service and lets you manage them.
	Models	Interface to help you build models. A model represents data stored from another source.
	Configuration	Lists configuration files that you can modify and save within a browser.
	Credentials	Lists the currently configured credentials.
	Plugins	Lists available and installed plugins 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.
	Sidebar toggle	Toggles the width of the sidebar.

To quickly navigate to the Summary tab, click on the Axway icon or click on API Builder.

Advanced startup

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:

// 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:

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

Further reading

Once you are familiar with startup and the UI, be sure to read the Best Practices guide as it will help guide your next phase of development.