Getting started
5 minute read
Prerequisites
You should have npm (recommended minimum 8), and Node.js (recommended minimum v16) installed.
The latest version of API Builder maintains compatibility with a minimum of Node.js v16, however, using a version older than v16 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.
Type | Development | Production |
---|---|---|
HDD | 110MB | 80MB |
RAM | 45MB | 40MB |
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.
// Install Axway CLI
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.
// Install API Builder
axway pm install @axway/amplify-api-builder-cli
Create a new API Builder project
Note
You can also create one of our pre-built example projects instead of creating a new one.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.
// Initialize a new project
axway builder init myproject
Then, start the API Builder project.
// Run 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:
// Install dependencies
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, and often contain important fixes and features (for more information about the updates, see API Builder Release notes). Follow the Update guide to keep your application up to date.
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:
// 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.
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.
For additional API Builder demos, examples and use-cases, check out posts on the Axway Blog.