v4 release notes

Summary

API Builder v4 enables customers to install and run API Builder in containerized environments. Previously, API Builder could only be installed in a cloud environment. For information on installing and getting started with API Builder v4, refer to the Getting Started With API Builder. The API Builder v4 release includes the following changes and new features to implement the ability to install API Builder on-premise. The release also includes breaking changes, fixed issues, known issues, and security vulnerabilities.

Upgrade

For more detailed instructors on how to migrate to API Builder v4, please follow the API Builder v3 to v4 Upgrade Guide.

Breaking changes

• Node Handlers from API Builder v3 are no longer compatible with API Builder v4. Node Handlers are now referred to as Flow-Nodes.
• API Builder no longer loads Node Handlers from the ./nodehandlers directory.
• Existing Node Handlers are renamed and installed as flow-node plugins. More information can be found here.
• The Admin UI has been removed from the API Builder runtime and should be installed as an explicit development dependency: npm install --save-dev @axway/api-builder-admin@^1.0.0
• The Appc CLI is no longer used to initialize, run or deploy API Builder v4 services. @axway/api-builder is the new CLI which should be used to create new projects. appc run is no longer required, replaced with directly starting your service with node app.js. npm install is now explicitly required before API Builder can start in order to pull the required dependencies from npm.
• The minimum required version of NodeJS is now 8.9.
• The prefix of Model flow-node IDs has changed from nodehandler://arrow-flow-invoke to nodehandler://api-builder-flow-invoke.
• Previously, without logLevel defined in the configuration, the default level would be ’trace’, now it is ’none’. New projects are generated with logLevel defined as ‘debug’.
• Previously, API Builder used different API keys based on the environment in which the service was running. These were accessible in default.js as apikey_development, apikey_production and potentially apikey_preproduction. Now, a single value apikey is used instead. If the value still needs to be changed per-environment this value should be configured using an environment variable instead.
• Previously, a number of appc_ prefixed variables were available in API Builder Web, used for accessing environment and platform-specific information such as the environment and host. Now, these variables have been removed and should be accessed in an alternative way.
• The /arrowPing.json endpoint has been renamed to /apibuilderPing.json. (Note that this has been re-added in the Barcelona.
• Previously, configuring the API Builder port by setting it to 0 would let the service start on any available port. Now, the feature has been removed and the configured port must be valid and available.
• Previously, in config, baseurl could include the port as well as the hostname. Now, it is more strict and should not include the port.
• #4075: Previously, API Builder loaded Service Connectors from the ./serviceconnectors directory. Now, they are no longer supported.
• #4390: Previously, API Builder loaded Data Connectors from the ./connectors folder of your project or the ./node_modules/connectors folder. Now, API Builder loads Connectors as API Builder plugins which should be installed as npm package dependencies and accessible from ./node_modules.
• #4390: Data connectors from API Builder v3 are no longer compatible with API Builder v4. The Appc CLI is no longer used to install connectors. For a list of available Data Connectors in API Builder v4 and how to use them, refer to API Builder Connectors.
• #4225: Previously, it was possible to specify environment variables from the operating system environment and apply them to the API Builder runtime (for example, ARROW_PORT). Now, it is no longer possible to automatically use ARROW_* environment properties. Instead, the configurable environment properties need to be explicitly included in the API Builder’s configuration files (for example, conf/default.js), and reference the environment variable by name (for example, process.env.APP_PORT).
• #4225: Previously, it was possible to have multiple sets of configuration files, for example, “development”, “production”, and so forth. Now, only two sets of configuration files are recognized: “default” and “local” (for example, default.js, foo.default.js,local.js, and foo.local.js), where the local config files are ignored by Git and npm.
• #4348: Previously, API Builder would write aggregated transactional logs to ./logs. Now, API Builder logs everything to the console and as a result, the logging in conf/default.js is no longer used. The existing logging configuration will have no effect on the application and can be removed safely.
• #4390: Previously, Data Connector configuration would use the connector name as the key; for example, appc.mysql, and then list specific configuration properties for the connector, including an optional alias. Now, the Data Connector configuration will use the user-configurable alias as a key; for example, mysql. The property connector is now required and must be set to the package name of the Data Connector being used.

mysql: {
  connector: '@axway/api-builder-plugin-dc-mysql',
  user: 'root',
  password: 'root'
}

• #4577: Previously, the Swagger generated for model CRUD APIs accepted additional properties in the request. This could lead to errors and unexpected behavior. Now, the APIs do not accept additional properties and they precisely define their return type in the id field.
• #4781: Previously, the API Builder runtime was in a module called arrow and was referred to as Arrow. Now, the API Builder runtime is in a module called @axway/api-builder-runtime and is referred to as APIBuilder.
• #4781: Previously, the API Builder React engine was in a module named arrow-react-engine. Now, the API Builder React engine is in a module called @axway/api-builder-react-engine.
• #4152: Previously, the methods on the model flow-nodes outputted Arrow.Model objects to the Flow context. Interacting with these in subsequent flow-nodes required a knowledge of the internal workings of the Model object. Now, the model flow-nodes output plain data objects containing the fields and values from the model method. This will only cause issues for flows that were expecting the Model object rather than a data object.
• #4368: Previously, the distinct method on flow-nodes for connectors had parameters for sel and unsel that were ignored. Now, these parameters are removed from the model flow-node.
• #4550: Previously, endpoints with query parameters accepted page and per_page as well as skip and limit. The problem is that it was not clear how to effectively use these. To exacerbate the issue, supplying both sets of parameters would yield unexpected result ranges. Now, page and per_page parameters have been removed since their functionality is a subset of what can be provided by the skip and limit parameters. In the backend, page and per_page are computed via skip and limit so connectors that rely on them should continue to function.
• #4602: Previously, model fields with default values would get set in the model schema without validation or interpretation. Now, the default values are validated to ensure that they are cast as the correct type.
• #4712: Previously, models would auto-generated API with optional body parameters for the Create, Upsert, Update, and Find and Modify methods. Now, body parameters are required.
• #4732: Previously, there was a serialization.exposePrimaryKeyAsId configuration option that was intended to force the primary key of a model to always be called id. Now, this configuration option has been removed and the model primary key field will always be exposed using its actual column name.

Features

• #1243: Previously, flows had no inputs and would receive implicit runtime parameters $.params, $.request, $.config, and $.env for use at runtime. Now, those parameters are explicitly part of the flow definition.
• #1243: Previously, “Generate endpoints” from a model would generate Flows that had implicit $.params, $.request, $.config, and $.env inputs for use at runtime. Now, the generated Flows only use the explicit API endpoint parameters needed to execute the model function, e.g. $.limit and $.where.
• #4045: Previously, the flow editor UI had a Save button that would save the current flow being edited and then exit to the list of API methods. Now, the flow editor UI has an Apply button that allows the flow to be saved, but stays in the flow editor and does not exit. The Cancel button has also been renamed to Close. If the flow has no changes, then Close will just exit. If the flow has changed, then Close will prompt to save or discard changes before exiting.
• #4346: Previously, projects created with the Axway Flow SDK had to synchronously export their flow-node specifications which prevented the use of asynchronous APIs, such as network calls or complex parsers, when generating the flow-node specifications. Now, API Builder allows the flow-node projects to export a Promise which will resolve with the flow-node specification, allowing for asynchronous loading of the flow-node specifications. Now, this is the default behavior in all new flow-node projects.
• #4392: Previously, the appc.composite Connector was installed separately into your application. Now, the Connector has been renamed to composite and is now included as part of API Builder with no need to install it separately.
• #4524: Previously, when a Flow was invoked it would log the step-by-step execution with only the flow-node’s ID which was not very user-friendly. Now, Flow logging will include the user-provided flow-node name alongside the ID. For example, Format String (mustache.1).

Fixes

• #4350: Previously, importing API endpoints into API Builder would incorrectly apply a Content-Type to GET methods. Now, imported endpoints do not apply Content-Type to GET methods.
• #4350: Previously, API Builder would apply consumes, produces, tags, schemes, and security properties on the service’s Swagger document. This would unintentionally mean that any endpoints without these properties defined per-path, would take these global values instead of their intended value. Now, any endpoints which are imported with any of these properties will only have them applied to that endpoint’s methods, and API Builder will not apply any of these properties globally which could change the meaning of the resulting Swagger document.
• #4355: Previously, HTTP method verbs in the API Documentation page for endpoints were lower-case. Now, they are correctly displayed in upper-case.
• #4363: Previously, importing a Swagger document with an empty title would save the file to endpoints/*.json. This is because the file name is derived from the title. Also, if a file already existed with the desired name, an error would be thrown. Now, the imported file name or URL basename will be used if the Swagger title is blank. Additionally, if the desired filename already exists, then the imported filename will have an integer appended to it to ensure uniqueness.
• #4368: Previously, the model generated API for distinct had options for sel and unsel that were ignored. Now, these options are not added to the API.
• #4531: Previously, query parameters in the Swagger generated from models were missing some maximum, minimum, and default properties. These are used to set parameter defaults and to enforce correct user input. For example, the page query parameter should be set to a minimum value of 1. Now, these values are part of the generated query parameters.
• #4559: Previously, when running an API Builder project that began with the character “u” on Microsoft Windows, the service would fail to start with a SyntaxError: Invalid Unicode escape sequence. Now, these projects will start correctly.
• #4578: Previously, after importing a Swagger API, when trying to invoke an API method that consumes a body, where the consumes parameter was not defined in the original Swagger document (either on the method, or globally), API Builder would return “Request validation failed: Parameter (body) failed schema validation”. Now, API Builder applies a default consumes parameter of application/json. The Swagger 2.0 specification does not explicitly handle this condition but their own tooling applies application/json and it is a reasonable assumption that the method can default to application/json when the body must validate against a JSON schema.
• #4732: Previously, the primary keys on models had to be named id. Now, API Builder supports primary key columns with names other than id.

Notable connector fixes

MySQL

• #4368: Previously, calling query on the MySQL connector with sel containing an unknown field would have indeterminate results and would be potentially dangerous for SQL injection attacks. Now, unknown fields are filtered out and will return an error.
• #4368: Previously, calling query on the MySQL connector with order containing unknown columns would have indeterminate results and was open to SQL injection attacks. Now, using order with an unknown column will return an error.
• #4368: Previously, calling distinct on the MySQL connector with an unknown field would have indeterminate results and would be potentially dangerous for SQL injection attacks. Now, an unknown field will return an error.
• #4368: Previously, calling query, distinct, count, or findAll on the MySQL connector with a where option that contained unknown columns would have indeterminate results and was open to SQL injection attacks. Now, using the where option with an unknown column will return an error.
• #4368: Previously, calling distinct or findAll on the MySQL connector would not honor options for order, skip, or limit. Now, these options are honored.
• #4368: Previously, calling upsert on the MySQL connector with an un-escaped ID value would have indeterminate results and would be potentially dangerous for SQL injection attacks. Now, ID is passed as a placeholder and escaped.
• #4548: Previously, the MySQL connector did not support the decimal type. Now, support has been added for decimal table fields and converts them to a number in the corresponding JavaScript model.

Mongo

• #4700: Previously, the distinct method for Mongo database collections did not honor skip, limit, or order query parameters. Now, the distinct method for Mongo database collections honors skip, limit, or order query parameters.

Previous releases