API Builder Environment Variables

An environment variable is a dynamic-named value that can affect the way running processes will behave on a computer. Since API Builder is used to create APIs to back-end systems, one important use of environment variables is to hold credentials for back-end systems that would otherwise be hard-coded into your API Builder project. Another benefit to using environment variables is that they provide an easy way to change the variable’s value without having to re-deploy (publish) the API Builder project.

This blog post will discuss some ways to use and set environment variables in an API Builder project.

Using environment variables in your API Builder project

Since an API Builder project is a Node.js project, environment variables are used/accessed the same way. Therefore, accessing environment variables in API Builder is supported right out of the box. When your API Builder project boots up, it will automatically provide access to all existing environment variables by creating an env object as property of the process global object:

process.env

Later, we will see how to create our own environment variables, so if we create and set an environment variable called MYVAR, it would be accessed as follows:

process.env.MYVAR

Setting environment variables in your API Builder project

An API Builder project has several modes that it can run in – locally on your machine in dev mode or in a runtime environment, e.g. production. Your production API Builder project can run in several types of production environments, such as the Axway Public Cloud, the Axway managed cloud (VPC – virtual private cloud) or, for the recently introduced API Builder Standalone, in a docker container (private cloud).

Let’s see how to set API Builder environment variables for all of these scenarios.

Development mode

When you develop and run your API Builder project on your local machine (i.e. using ‘appc run’), you are in development mode. In this case, setting environment variables is done by adding the environment variable to the command line used to run the API Builder Project as follows:

MYVAR=9000 appc run

Note that in the example above, I am setting the environment variable, MYVAR to the value of 9000.

Note that this assumes that you are running on a Mac or Linux machine. If you are running on a Windows machine, use the SET command to set your environment variables separate from the run command

Let’s try this out as follows:

Create a new API Builder Project
Edit the app.js file and add the following line to the server.on ‘starting’ callback function:

console.log('MYVAR = '+process.env.MYVAR);

as follows:

server.on('starting', function () {
server.logger.debug('server is starting!');
console.log('MYVAR = '+process.env.MYVAR);
});

Run your project using the following command line:

MYVAR=9000 appc run

You should see something similar to the following in the console:

$ MYVAR=9000 appc run
Appcelerator Command-Line Interface, version 7.0.1
Copyright (c) 2014-2018, Appcelerator, Inc.  All Rights Reserved.

INFO   | API Builder Tools/3.0.0 lbdemoapi2/1.0.0
INFO   | APIKey is: AY22QPrcvHXc0CsPMVrdSaDZvlbgG4UZ
INFO   | Starting connector/appc.arrowdb@1.1.11
INFO   | Started connector/appc.arrowdb
INFO   | Starting connector/appc.composite@2.0.1
INFO   | Started connector/appc.composite
INFO   | Access the swagger API documentation at https://localhost:8080/apidoc/swagger.json
INFO   | Access to API Builder Console restricted to: 127.0.0.1, ::1, ::1
INFO   | Access API Builder Console at https://localhost:8080/console. This will only be available on your dev environment.
MYVAR = 9000
INFO   | server started on port 8080

Notice the line ‘MYVAR = 9000’ just before the last line.

Note that for API Builder 4.0 (a.k.a. “standalone”) use MYVAR=9000 npm start to run your project locally

Production mode

You would be tempted to use the same technique of setting environment variables for your published API Builder project, e.g. MYVAR=9000 appc publish, but you would be sadly disappointed. Instead, we use the appc cloud config command as follows:

appc cloud config --set MYVAR=9000

So, how/when do we use this command? Here is one approach:

Publish your project using appc publish
Use the appc cloud config command to set your environment variable(s)
You will be prompted that your project needs to be restarted, type yes

Note that if your project will crash with an undefined environment variable, then you may want to adjust for this using process.env.MYVAR || {some default value} in your code

When I published the default API Builder project with the small console.log modification described above, the logcat (appc cloud logcat) displayed the following:


...
2018-09-20T18:25:56+00:00 | DEBUG  | attempting to load route /opt/app/web/routes/example.js
2018-09-20T18:25:56+00:00 | DEBUG  | starting 80
2018-09-20T18:25:56+00:00 | DEBUG  | server is starting!
2018-09-20T18:25:56+00:00 | MYVAR = undefined
2018-09-20T18:25:56+00:00 | DEBUG  | port undefined available for use
2018-09-20T18:25:56+00:00 | DEBUG  | loading schemas
2018-09-20T18:25:56+00:00 | DEBUG  | loading 9 schema
...

Note that MYVAR is undefined since we have not set it yet.

Now we can use the following command to set the MYVAR environment variable:

appc cloud config --set MYVAR=9000

When prompted:

Making changes to environment variables will restart your app. Proceed [yes/no/always]:
type yes and press enter.

Now, view the logcat and you will see something similar to below:


...
2018-09-20T18:31:38+00:00 | DEBUG  | attempting to load route /opt/app/web/routes/example.js
2018-09-20T18:31:38+00:00 | DEBUG  | starting 80
2018-09-20T18:31:38+00:00 | DEBUG  | server is starting!
2018-09-20T18:31:38+00:00 | MYVAR = 9000
2018-09-20T18:31:38+00:00 | DEBUG  | port undefined available for use
2018-09-20T18:31:38+00:00 | DEBUG  | loading schemas
2018-09-20T18:31:38+00:00 | DEBUG  | loading 9 schema
...

Now, you can see that the environment variable was set to 9000 properly.

API Builder 4.0 (Standalone)

An example of setting environment variables for API Builder 4.0 (Standalone) was described briefly in the API Builder 4.0 Standalone – From Zero to Dockerized Microservice blog post.

Connector example

As described in the introduction, environment variables are very useful for backend credentials. For example, you need backend credentials when configuring connectors. Below is an example of a Salesforce connector configuration file with environment variables:


/**
 * Example configuration for connector/appc.salesforce.
 * Make the changes below as required for your environment.
 */module.exports = {
  connectors: {
    'appc.salesforce': {
      /*
      requireSessionLogin allows you to configure whether or not anonymous requests can use your default
      account (specified below) for connecting to Salesforce. Set this to "true" to require requests to specify
      their own credentials or their own session token (via the headers user, pass, and token, or accessToken).
      */      requireSessionLogin: false,

      /*
      Configure how to connect to your instance; this will be used for looking up metadata and,
      if requireSessionLogin is false, for executing methods.
      */      url: 'https://test.salesforce.com/',
      username: process.env.SFUN,
      password: process.env.SFPWD,
      token: process.env.SFTOKEN,

    /*
      Other settings.
      */      schemaRefresh: 3.6e+6 * 24, // how long the cache will live (one day); set to "false" to disable caching.

      // Create models based on your schema that can be used in your API.
      generateModelsFromSchema: true,

      // Whether or not to generate APIs based on the methods in generated models.
      modelAutogen: false

      // If you want to use a specific version of the Salesforce API, uncomment and customize the following:
      // version: '26.0'

      // If you only want to generate a couple of models from the schema, uncomment and customize the following:
      /* generateModels: [
        'Account',
        'Contract'
        ] */    }
  }
}

To run this project, I need to define SFUN, SFPWD and SFTOKEN environment variables.

During development, I can use:

SFUN=<your_salesforce_username> SFPWD=<your_salesforce_password> SFTOKEN=<your_salesforce_token> appc run

In production, I can use:

appc cloud config --set SFUN=<your_salesforce_username>,SFPWD=<your_salesforce_password>,SFTOKEN=<your_salesforce_token>

Using the dotenv npm package

It is worth noting that if you have a lot of environment variables, you can store them in a .env file that you won’t check into source control. You can use the dotenv npm in your API Builder project and add the following line to your project, for example, in your connector config file (or wherever your environment variables are required):

require('dotenv').config();

Summary

In this blog post, we looked at how to use environment variables in your API Builder project in order to protect back-end credentials.

Share this article: