API Builder Best Practices

API Builder is a low-code / no-code developer application that you use to design and build a service using secure, modular, and re-usable components. When used correctly, it can be a very powerful useful tool in your organization. Below are a list of some suggestions to help you get the most out of API Builder. For further reading on generic best practices for microservice development and deployment, be sure to check out the twelve-factor app methodology, which this guide has borrowed from. If you have any questions or feedback, you can use Axway's support portal.

Codebase

  • Use version control.
  • For development, API Builder requires access to an npm repository (or registry.npmjs.org mirror). We do not recommend using offline archives of dependencies.
  • Keep your application small, and with single responsibility. Smaller applications are easier to develop, debug, manage and understand.
  • Keep your codebase clean and remove things that you are not using (e.g. log files, flows, API, endpoints, models, etc.).
  • We recommend that API Builder is developed on a local development machine. We do not recommend an "online" shared-server approach to development where API Builder is installed on a machine that many developers access.

Dependencies

  • Understand semantic-versioning.
  • Understand npm dependencies and dev-dependencies and how to use them appropriately. By default, your API Builder application is configured to get the latest features and patches on npm install/update.
  • Uninstall dependencies that you are not using. These add to bloat, make your application bigger, and slower to install.
  • Use security tools such as npm-audit to ensure your dependencies do not contain any vulnerabilities. API Builder uses npm-audit, Fortify, SonarQube, and WhiteSource to ensure code quality on our code and our dependencies.
  • Use package-lock or shrinkwrap when developing to ensure the same dependency tree.
  • If using package-lock then you should use the npm ci command instead of npm install for faster installation.

Configuring and securing your application

  • Separate config from code. Do not hard-code configuration parameters that will need to change in different environments, such as: hosts, URLs, credentials, timeouts, etc. Instead, manage configuration separately from your code. The easiest way is to use our Environmentalization guide. It is compatible with our Docker.
  • Never hard-code credentials in the application. Use our Authentication Schemes to learn how to configure authentication, our Environmentalization Guide to learn how to use environment parameters, and our Credentials guide for configuring credentials.
  • Never use a template (e.g. mustache, XSLT, doT) from an untrusted source. These can compromise your service's integrity.
  • Do not disable API acessControl security.
  • Log at info level in production (for more information about logging modes, see Logging). Do not log sensitive information in at info level. Note that in development mode, API Builder will log at debug level ((warning) this includes sensitive information) for debug/development purposes.

Design and develop

  • Decide on an API development strategy. API Builder supports API first with drag-and-drop flow nodes (the recommended approach), model approach (connecting to a DB and generating a rich CRUD API from existing tables and views), or a custom API approach (write a pure JS API, but we would advise against this approach).
  • If using API first approach, employ Axway's API first philosophy. This ensures that you design your API to suit the customer. API Builder supports Swagger 2.0 API definitions as the front-end API to your application. These can be used to define a rich customer-facing API documentation. Once defined, you can bind Flows to the existing Endpoints and use our drag-and-drop flow editor to implement your API.
  • From the UI, you can find many API Builder plugins on Plugins page. These extend the capabilities of API Builder. Be sure to check the available plugins for functionality before attempting to write your own implementation.
  • If you cannot find the capabilities you need on our Plugins page, you have a choice: use the JavaScript flow-node if it is a relatively simple fragment or if you need to produce a template, or use the API Builder SDK to write a custom flow-node that can be reused between your API Builder services.
  • We recommend that you connect to external services using Swagger 2.0 and OAS 3.0 using our @axway/api-builder-plugin-fn-swagger flow-node.
  • When implementing your Flows, ensure all outputs are handled (e.g. Error).
  • We recommend that you implement your API to be as fast as possible. If API calls take too long, these can tie up resources and lead to unexpected timeouts.
  • If API calls take too long, consider an event-driven architecture using Flow-Triggers and a message queue plugin, such as Solace or Kafka.
  • Strive to make your application stateless as much as possible. This improves speed, scalability, and robustness.

Custom flow-node develoment

When writing code for the JavaScript flow-node, or writing a custom flow-node using our SDK, we recommend the following:

  • Learn JavaScript and Node.js. Note that JavaScript in web browsers has differences compared to Node.js which has a slightly different API.
  • Use Mozilla Developer Network (MDN) for your JavaScript reference as it is a complete/accurate resource. 
  • Use the official Node.js documentation to see the features and behavior of the particular version of Node.js that you are using. Some parameters that you provide to API Builder may be configuring Node.js features.
  • Learn modern JavaScript ES6 (ECMAScript 6) and higher (there's new features every year!) as this will save you time and make your code easier to maintain and super-charge your Flow development. Note that the supported features are down to the version of Node.js that you are using. Check node.green for ECMAScript feature support.
  • Do not mix tabs and spaces - this will drive people crazy. Your initial API Builder project's files are all tab based. Pick one, and stick with it.
  • Use a linter to ensure code conformity and bug detection (we recommend eslint).
  • We recommend mocha for your unit-tests.
  • We recommend simple-mock to mock interfaces you don't need to test (e.g. fs) or that you wish to force errors.
  • We recommend nyc for calculating code-coverage (we strive for 100% coverage).

Testing your application

  • Write unit-tests for all API endpoints and run them as part of your CI (in the ./tests directory, you will find examples of how to test the example Greet endpoint). We recommend mocha.
  • Learn how to debug a flow.
  • Use curl or postman for bespoke API requests.

Production

  • Secured with TLS or SSL termination (depending on deployment architecture).
  • Use docker to containerize your application.
  • Use security tools to scan your containers to ensure they do not have open ports or security vulnerabilities.
  • Use npm install with the --production flag.
  • We recommend you use docker and not run as a stand-alone service (e.g. as opposed to running on a VM) so that it can be managed and scaled efficiently.
  • We recommend that you use API Central if you need to expose your service to the Internet.
  • Set NODE_ENV=production in the environment for security and performance.

Maintaining your service

  • Use the latest, fully-patched version of node that we support (see our Getting Started Guide and API Builder Node.js support policy for version restrictions).
  • Keep your dependencies up to date with their latest patches.
  • Every two weeks, Axway API Builder releases new features, patches, and security fixes. You should keep an eye on our Release Notes and list of Deprecations. Keep abreast of the updates to ensure your application will be compatible with any change(s) that may be introduced. Occasionally, you may want to incorporate these security updates and fixes into your application.

 

Related Links