API Builder Getting Started Guide

Prerequisites

You should have NPM (recommended minimum v6.13), and Node.js (recommended minimum v12.16 LTS) installed.

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

Getting started

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

Install the AMPLIFY CLI

Install the AMPLIFY CLI globally using npm. Refer to the AMPLIFY CLI documentation for more details.

[sudo] npm install --g @axway/amplify-cli

Verify the AMPLIFY CLI installation by running the following command.

amplify pm list 

Install the API Builder CLI

Install the API Builder CLI.

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

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.

amplify builder init myproject

Then, start the API Builder project.

cd myproject
npm start

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

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:
   
   
   1. Enter "simpleuser" in the Model name field (required). The name must be unique for all of the application's models.
   2. Select a Connector from the drop-down list (required). Connectors are used to persist data to the model.
   3. Add a description.
   4. Click Next to move onto the fields step.
4. In the Create Model Fields step:
   
   
   1. Click the + Field button.
   2. Enter "first_name" in the Field name field (required).
      
   3. Set Type to String.
   4. Leave Default value empty.
   5. Add a description.
   6. Check the boxes for Read-only or Required as necessary.
   7. Click the Add field to model button.
   8. 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.
   9. Click Next to move onto the endpoint step.
5. In the API endpoint page:
   
   
   1. Make sure the Create, Retrieve, Update, and Delete methods are checked.
   2. 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:

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