API Builder v3 vs v4

Over a year ago, we launched API Builder 4 (Standalone). Our goal with this new version was to allow users the freedom to deploy their APIs wherever they liked. Users can still deploy their work to AMPLIFY Runtime Services (ARS), but they can now deploy services as containers on their own platforms.

API Builder 4

In addition to that, we developed API Builder to become a much more sophisticated flow engine, with easy integration with other REST services and is more CI/CD friendly (see 4.0.0 Release Notes). For most users, upgrading from v3.x to v4.x is a relatively simple process and is described in the API Builder v3 to v4 Upgrade Guide.

By switching to v4.x, you can ensure that you receive bleeding edge improvements in your experience. We provide new fixes and features in v4.x every two weeks. Our releases are alphabetical and are named after cities (see the latest 4.x Release Notes).

In this blog, we will highlight some key features of API Builder v4.x and describe how the v4.x experience differs from v3.x.

Key API Builder Features

Rapid integration

API Builder is a Node.js service using Express.js that provides a low-code/no-code interface to build rapidly integrations with existing databases and external services.

Docker containers

Your v4.x services can be built into Docker containers, which can run anywhere, including AMPLIFY Runtime Services (ARS), enabling you to use modern CI/CD pipelines. You can still use API Builder v4.x without Docker.

Flows

Flows are a pluggable a-cyclical directed graph that manages asynchronous calls between flow-nodes that provide operations to manage and manipulate data. A simple drag-and-drop UI and an SDK allow you to build custom and robust integrations to legacy applications.

REST API from databases

Using database connector plugins, API Builder will scrape schema and generate Models that provide Object Relational Mapping ORM capabilities. The Models can be used within Flows or can be used to generate a rich CRUD API that is Swagger 2.0 compliant.

Exposes a Swagger/OpenAPI 2.0 compliant API

The API Builder v4.x service exposes a Swagger/OpenAPI 2.0 compliant API that documents your service interface and facilitates writing clients to interact with your service.

AMPLIFY Platform

Using the API Builder Amplify CLI, you can build integrations to your existing services via the Amplify Platform, giving you hybrid connectivity to services from ground to cloud.

Rapid integration with Swagger 2.0 services

The Swagger flow-node supports easy integration with existing Swagger 2.0 (OpenAPI) services.  In addition, Credentials enable you to manage the authorization for these services.

Credentials

Credentials are a way for you to manage your access to services that require authorization (e.g., OAuth 2.0, API Key, etc.). An integrated credential manager will auto-refresh OAuth 2.0 credentials, allowing your service to connect and stay connected.

Understanding the v4.x experience for v3.x customers

Although the v4.x stand-alone experience differs greatly from the v3.x experience, which was connected to the Appcelerator platform, the new experience is much more flexible than before.  If you are used to v3.x API Builder, there are key differences highlighted below to get you quickly acclimated to the v4.x way of doing things.

Creating new projects

In API Builder v3.x, applications were created using the appc command-line tool. In v4.x, there is a new command-line tool that does not require a login and is used to create new applications.  In v4.x, we recommend that you use the API Builder command line with npx, rather than install the command line globally. This ensures that you always have the latest features.

$ npx @axway/api-builder init myproject

Managing dependencies

In v4.x you install and manage all dependencies using a package manager such as npm. In v4.x, the API Builder runtime is an explicit dependency of your project.  In addition, the Admin UI is a dev-dependency. The Admin UI should never be installed or run in production. All the API Builder connector plugins and flow-node plugins are node modules and can be managed independently. For example, to install the Oracle connector plugin.

$ npm install @axway/api-builder-plugin-dc-oracle

If you used ArrowDB in v3.x, this experience has changed significantly in v4.x.  ArrowDB is now called Mobile Backend Services (MBS) and is installed using a new connector plugin.

$ npm install @axway/api-builder-plugin-dc-mbs

It is important that you read the API Builder v3 to v4 Upgrade Guide to learn more about the differences.  One of the key differences is that it only supports custom objects.

Running your application

The API Builder runtime (@axway/api-builder-runtime) is an explicit project dependency. An npm start script can be used to run your application.

$ npm start

To exit your application, you use Ctrl-Break.

Logging

One of the key differences in v4.x is that all logs are written to console, as opposed to writing files to a log directory in v3.x. When developing, you will likely need to see the console log to debug.

Debugging your application

From time to time, it is necessary to debug your application. This will directly invoke the main project file (app.js) with a breakpoint. This document will help guide you – we recommend using Chrome.

$ node --inspect-brk

Also, you should keep an eye on your console log as it can contain important runtime information that will help you debug.

Environments

In v3.x, your application could be configured to support many environments, e.g. “development” and “production” via configuration files that would automatically load, depending on the environment in which your application was run.  In v3, this was not a good thing – it encouraged bad practices, such as adding credentials to configuration files, and bundling configuration the application.

V4.x addresses this by making it easier for you to create a single application that can run in any environment. This guide describes the process in detail.

Building a Docker container

The v4.x project comes with an example Docker file. You can modify it to suit your needs. If you upgraded from v3.x, you may not have this file. You only need to build a container if you wish to deploy it to a runtime environment that supports them, including ARS.

$ docker build

Publishing your application

With Docker, you can run your containers anywhere, including a new feature that allows you to run your containers on ARS.