Project Configuration

Introduction

API Builder uses the configuration files in the project's conf directory to initialize the application and its connectors. Each JavaScript file in the directory should expose an object of key-value pairs. You may add any arbitrary key-value pair beside the one described below. The values will be passed to any method that is passed the API Builder configuration object.

Icon

API key values and session objects are auto-generated when you create a new project.

Example configuration file:

./conf/default.js  Expand source
/**
 * These are your configuration file defaults.
 *
 * You can create additional configuration files ending in *.default.js or
 * *.local.js that the server will load. The *.local.js files are ignored by
 * git/npm due to the .gitignore file in the conf directory. Docker will also
 * ignore these files using the .dockerignore file in the project root. This
 * is so you can develop your service locally using *.local.js files and keep
 * your production configs in the *.default.js files.
 *
 * For example, you may want to develop your service using a test API key. You
 * would place that API key in a *.local.js file and it would get merged over
 * the API key that is already present in default.js
 *
 * This is a JavaScript file (instead of JSON) so you can also use environment
 * variables or perform logic in this file if needed.
 */
module.exports = {
	// This is your generated API key.  It was generated uniquely when you
	// created this project. DO NOT SHARE this key with other services and be
	// careful with this key since it controls access to your API using the
	// default configuration.
	// API key
	apikey: '<%=apikey%>',
	// This is the base url the service will be reachable at not including the
	// port
	baseurl: 'http://localhost',
	// Enabling this property will print out the process.env at startup time
	printEnvVars: false,
	// Proxy configuration. This configuration option allows to configure
	// proxy server URL that can be leveraged in plugins that do http/s
	// communication.
	// proxy: 'http://localhost:8081',
	// Configures your http server
	http: {
		// This is the port the service will be bound to. Defaults to 8080.
		port: process.env.PORT,
		// When this flag is set to true http is disabled.
		// For this to work `ssl` flag also must be configured and used.
		disabled: false
	},
	// SSL configuration. For a step-by-step tutorial on how to configure SSL see:
	// https://docs.axway.com/bundle/API_Builder_4x_allOS_en/page/enable_a_secure_https_listener.html
	// Note that the sample SSL code below uses the 'fs' and 'path' modules, e.g.:
	// const fs = require('fs');
	// const path = require('path');
	// ssl: {
	// 	port: 8443,
	//	key: fs.readFileSync(path.join('.', 'ssl','key.pem'), 'utf8'),
	//	cert: fs.readFileSync(path.join('.', 'ssl','cert.pem'), 'utf8'),
	//	passphrase: 'secret'
	// },
	// The number of milliseconds before timing out a request to the server.
	timeout: 90000,
	// Log level of the application. Can be set to (in order of most-verbose to
	// least): trace, debug, info, warn, error, fatal, none
	logLevel: process.env.LOG_LEVEL || 'info',
	// Prefix to use for APIs, access to which is governed via `accessControl`.
	apiPrefix: '/api',
	// Control access to the service.  Set the `apiPrefixSecurity` to change
	// the authentication security to APIs bound to `apiPrefix`.  Note that
	// different authentication security require different input parameters.
	// `apiPrefixSecurity` can be any of the following:
	//
	// 'none' - Disable authentication.  Note that this will make all APIs
	// hosted on `apiPrefix` public.
	//
	// 'ldap' - LDAP authentication.  Requires HTTP Basic Authentication
	// (RFC-2617) scheme with Base64 encoded username:password.  Also requires
	// specifying configuration property named `ldap`. It should be of type
	// object and should contain required property `url` and optional
	// properties described in ldapauth-fork module docs. See:
	// https://www.npmjs.com/package/ldapauth-fork#ldapauth-config-options
	//
	// 'apikey' - HTTP header authentication.  Requires a HTTP header `APIKey`
	// with the API key.
	//
	// 'basic' - This is the default.  HTTP Basic Authentication (RFC 2617)
	// where the username is the `apikey`, and the password is blank.
	//
	// 'plugin' - A custom authentication scheme. See:
	// https://docs.axway.com/bundle/API_Builder_4x_allOS_en/page/authentication_schemes.html#AuthenticationSchemes-Customauthentication
	//
	// If you wish any path that is not bound to `apiPrefix` to be accessible
	// without authentication, then you can explicitly add them to `public`
	// paths.
	accessControl: {
		apiPrefixSecurity: 'basic', // none | basic | apikey | ldap | plugin
		public: []
	},
	// Admin UI settings. Controls the settings for the
	// @axway/api-builder-admin UI console.
	admin: {
		// Control whether the admin website is available.
		enabled: true,
		// The hostnames or IPs from which connections to admin are allowed.
		// Hostnames must be resolvable on the server. IP ranges can also be
		// specified. e.g. [ 'localhost', '192.168.1.0/24', '10.1.1.1' ]. An
		// empty list [] will allow unrestricted access, though this is not
		// recommended due to security concerns.
		allowedHosts: [
			'localhost', '::1'
		]
	},
	// Swagger API documentation configuration.
	apidoc: {
		// If you disable, the swagger API documentation will not be available.
		// If @axway/api-builder-admin is installed and enabled, this has no
		// effect.
		disabled: false,
		// The prefix for the swagger API documentation. Documentation is always
		// available from '{prefix}/swagger.json'
		prefix: '/apidoc',
		// Overides for the Swagger API documentation.  These optional
		// overrides tweak how the API is generated, but not how it is hosted
		// (use `apiPrefix`, `port`, and `ssl` configuration instead).  This
		// allows you to tweak specific Swagger values that are useful when
		// the service is not consumed directly, such as when the services is
		// exposed through a proxy.  Available options are:
		//
		// schemes - The transfer protocol of the service. It is an array of
		// values that must be one or more of 'http', 'https', 'ws' or 'wss'.
		// e.g. ['https']
		//
		// host - The host (name or ip) serving the service. This MUST be the
		// host only and does not include the scheme nor sub-paths. It may
		// include a port.
		//
		// basePath - The base path on which the service is served relative to
		// the host. If provided, this MUST start with a leading slash, or be
		// null to specify not to use basePath.
		overrides: {
			// schemes: [ 'https' ],
			// host: 'localhost:8080',
			// basePath: '/'
		}
	},
	// You can generally leave this as-is since it is generated for each new
	// service you created.
	session: {
		encryptionAlgorithm: 'aes256',
		encryptionKey: '<%=session.encryptionKey%>',
		signatureAlgorithm: 'sha512-drop256',
		signatureKey: '<%=session.signatureKey%>',
		// should be a large unguessable string
		secret: '<%=session.secret%>',
		// how long the session will stay valid in ms
		duration: 86400000,
		// if expiresIn < activeDuration, the session will be extended by
		// activeDuration milliseconds
		activeDuration: 300000
	},
	// If you want signed cookies, you can set this value. if you don't want
	// signed cookies, remove or make null
	cookieSecret: '<%=cookieSecret%>',
	// Your connector configuration goes here
	connectors: {
	},
	// Cross-Origin Resource Sharing (CORS) settings.  The available options:
	//
	// 'Access-Control-Allow-Origin' - List of allowed origins.  The format can
	// be any (e.g. '*'), a space separated list of strings (e.g.
	// 'http://foo.com http://bar.com'), an array (e.g. ['http://foo.com',
	// 'http://bar.com']), or a regex expression (e.g. /foo\.com$/).
	//
	// 'Access-Control-Allow-Credentials' - Adds the header to responses.  This
	// response header tells browsers whether to expose the response to frontend
	// JavaScript code when the request's credentials mode
	// (`Request.credentials`) is `include`.
	//
	// 'Access-Control-Allow-Methods' - Only these methods will be allowed (out
	// of all available HTTP methods) for an endpoint. All available methods
	// are allowed by default (format: comma separated string or, an array:
	// e.g. 'GET' or 'GET, PUT' or ['GET', 'PUT'])
	//
	// 'Access-Control-Allow-Headers' - Allowed request headers (format: comma
	// separated string or, an array: e.g. 'content-type, authorization' or
	// ['content-type', 'authorization']) 'Access-Control-Allow-Headers':
	// ['content-type', 'authorization']
	//
	// 'Access-Control-Expose-Headers' - List of response headers exposed to the
	// user. Always exposed headers: request-id, response-time and any headers
	// defined in the endpoint (format: comma separated string or, an array:
	// e.g. 'content-type, response-time' or ['content-type', 'response-time'])
	// 'Access-Control-Expose-Headers': ['content-type', 'response-time']
	//
	cors: {
		// 'Access-Control-Allow-Origin': '*'
	},
	// Health check configuration. The path to a file which exports an express
	// middleware function used as a healthcheck. For more information on
	// express middleware functions, see:
	// https://expressjs.com/en/4x/api.html#middleware-callback-function-examples
	//
	// This healthcheck middleware is executed by invoking
	// "GET /apibuilderPing.json". By default, invoking this endpoint will
	// return {success: <bool>} where <bool> is `true` as long as the service
	// shutting down.
	//
	// healthCheckAPI: './healthCheck.js',
	// Flags configuration.  Enable features that are not ready for
	// production, or whose use may require manual upgrade steps in legacy
	// services.
	flags: {
		// Enable support for aliases in comparison operators on composite
		// models. Breaking change for old versions as previously queries $lt,
		// $gt, $lte, $gte, $in, $nin, $eq would not have translated aliased
		// fields.
		enableAliasesInCompositeOperators: true,
		// Enable support for the $like comparison operator in the Memory
		// connector.
		enableMemoryConnectorLike: true,
		// Enable support for Models that have no primary key. Breaking change
		// for old versions as previously the Create API returned a location
		// header. Also the model advertised unsupported methods.
		enableModelsWithNoPrimaryKey: true,
		// Generate APIs and Flows that user primary key type rather than always
		// assuming string. Breaking change for old versions as the generated
		// APIs will change when enabled.
		usePrimaryKeyType: true,
		// Enabling this flag will cause the service to exit when there is a
		// problem loading a plugin
		exitOnPluginFailure: true,
		// Enabling this flag ensures that a plugin only receives the config
		// relevant to that plugin.
		enableScopedConfig: true,
		// Enable support for null fields coming from Models
		enableNullModelFields: true,
		// Enable support for model names being percent-encoded as per RFC-3986
		// in auto-generated API. Breaking change for old versions as previously
		// names like "foo/bar" will now be encoded as "foo%2Fbar"
		enableModelNameEncoding: true,
		// Enable support for model names being percent-encoded as per RFC-3986
		// in API Builder's Swagger. Breaking change for old versions as
		// previously names like "foo/bar" will now be encoded as "foo%2Fbar"
		enableModelNameEncodingInSwagger: true,
		// Enable support for model names being encoded whilst preserving the
		// connector's slash. This flag only applies when
		// enableModelNameEncodingInSwagger is enabled. Breaking change for old
		// versions as previously model names that start with a connector name,
		// e.g. "oracle/foó" will now be encoded as "oracle/fo%C3%B3".
		enableModelNameEncodingWithConnectorSlash: true,
		// Enable support for overriding endpoint content-type using the flow's
		// HTTP response headers.
		enableOverrideEndpointContentType: true,
		// Enable support for model flow-nodes having Error outputs.
		enableModelErrorOutputs: true
	},
	authorization: {
		callback: '/auth/callback',
		credentials: {
		}
	}
};

  

Settings

The following topics describe the project configuration settings.

admin

[object] Configures the Admin Console. The admin object may contain the following key-value pairs:

Key Type Default Description
allowedHosts Array<String> - Restricts access to the Admin Console to the specified hosts.
apiDocPrefix String '/apidoc' Deprecated [D002]. Prefix for the API documentation.
disableAPIDoc Boolean false Deprecated [D003]. Set to true to display the generated Swagger API Docs. Changing the setting only works in production. Swagger documentation is always available in dev mode.
enabled Boolean true Set to true to enable the Admin Console.

apidoc

[object] Configures the Swagger API documentation since the API Builder Standalone - Boston release. The apidoc object may contain the following key-value pairs:

Key Type Default Description
disabled Boolean false Set to true to display the generated Swagger API Docs. Changing the setting only works in production. Swagger documentation is always available in dev mode.
prefix String '/apidoc' Prefix for the API documentation.
overrides object {} Overrides to Swagger documentation. Any values set here do not change the functionality of the server, only what is exposed in the Swagger.
overrides.host string - Hostname and optional port on which the server can be accessed.
overrides.schemes array - Schemes which the server can be accessed using. Can be an array containing any of http, https, ws, or wss.
overrides.basePath string - The root path on which the APIs hosted by the server are available. If provided, this must start with a leading slash (/). The value can be set to null to clear the basePath.

apikey

[string] Generated API key.

apiPrefix

[string] Required. Defaults to /api, and must start with a leading slash (/).

The apiPrefix forms the base of all secured API in the API Builder service that you are developing. Authenticated access to all APIs that are bound to apiPrefix is controlled via accessControl.

For example, the model "testuser" has its API bound to /api/testuser, the "testapi" has its API bound to /api/testapi, and the API endpoint examlple for Greet flow is bound to /api/greet.

The apiPrefix is an important consideration when you are designing your API for use as an API endpoint in API Builder.  You might design your API so that all methods start with /api.  For example, you might design your API as /api/v1/calendar.  However, when it is imported into API Builder, your path will be bound to /api/api/v1/calendar, which is not what you want.  To achieve the desired result, the API needs to be designed without the apiPrefix.  The recommendation is to design your API with a versioned basePath "/v1", and then design your paths; for example, "/calendar".  Your designed API, including its basePath, would have the method /v1/calendar, but when imported into API Builder, it would be accessible as /api/v1/calendar.

To clarify, your Swagger 2.0 for this API might look similar to this:

API design without API prefix
basePath: '/v1',
paths: {
    '/calendar': {
        get: {}
    }
}


accessControl

[object] Configures authentication access since the API Builder Standalone - Kobe release. The accessControl object may contain the following key-value pairs:

Key Type Default Description
apiPrefixSecurity string none Configures the authentication scheme to use on APIs that are hosted on apiPrefix. The built-in schemes are none, basic, apikey, and ldap. Also, it is possible to set this to "plugin" to provide custom authentication.
public array - An array of paths that are always accessible. The paths are prefixes, do not support any regex or parameterization, and should always start with a slash (for example, /foo). If "/foo" is a public path, then it is a path prefix ("/foo/") such that all children are also public (for example, "/foo/bar"). If admin UI is enabled, then /console and /adminapi are automatic public paths. If apidoc is enabled, then /apidoc (apidoc.prefix) is also added.
plugin string - When apiPrefixSecurity is set to "plugin", this should be the plugin module to load (see Custom Authentication).

APIKeyAuthPlugin

[string] Path to the authorization module js file. Only used if APIKeyAuthType is set to plugin.

 For details, see Authentication Schemes. This key is deprecated [D010], use accessControl instead.

APIKeyAuthType

[string] Value indicating the authorization type for the application. By default, it is set to 'basic'.

 For details, see Authentication Schemes. This key is deprecated [D010], use accessControl instead.

connectors

[object] Configures the connectors used by the application. The connectors field is an object of key-value pairs where the key is the name of the connector, and the value is another key-value pair object used to configure the connector. The configuration object is specific to each connector.

Most connectors will have a default configuration file in the conf directory.

cookieSecret

[string] If you want signed cookies, you can set this value. If you don't want to sign cookies, remove this value, or make it null.

cors

[object] Configures the CORS settings. The cors object may contain the following key-value pairs:

Key Type Description
Access-Control-Allow-Origin String Specifies the URI that can access the server. Defaults to none.
Access-Control-Allow-Credentials Boolean Specifies whether or not to allow access by credentials.
Access-Control-Allow-Methods String<comma separated or array> If specified, only the listed methods will be allowed. All available methods are allowed by default.
Access-Control-Allow-Headers String<comma separated or array> Allowed request headers.
Access-Control-Expose-Headers String<comma separated or array> List of response headers exposed to the user.

proxy

[string] Configuration option for configuring the proxy server URL that can be leveraged in plugins that do HTTP or HTTPS communication.

Example:

 proxy: http://localhost:8081

flags

[object] Flags to enable features that are not ready for production or whose use may require manual upgrade steps in legacy services.

Key Type Description
enableAliasesInCompositeOperators Boolean Enable support for comparison operators - $lt, $gt, $lte, $gte, $in, $nin, $ne, and $eq - on aliased fields in Composite models. Previously, attempting to use these operators on aliased fields would result in unexpected behavior. The old functionality is deprecated [D007],  so enabling this feature is recommended.
enableMemoryConnectorLike Boolean Enable $like comparison operator support in models based on the Memory connector. Previously, attempts to perform these queries would just have returned an empty result set. The old functionality is deprecated [D008], so enabling this feature is recommended.
enableModelsWithNoPrimaryKey Boolean Enable support for Models that do not have a primary key. The enableModelsWithNoPrimaryKey feature is a breaking change for previous API Builder Standalone versions, as Create API previously returned a location header. Also, the model advertised unsupported methods. The old functionality is deprecated  [D004], so enabling this feature is recommended.
usePrimaryKeyType Boolean Generate APIs and Flows that use primary key type for the Model ID instead of assuming that the Model ID is a string. The usePrimaryKeyType feature is a breaking change for previous API Builder Standalone versions, as the generated APIs will change when the feature is enabled. The old functionality is deprecated [D005], so enabling this feature is recommended.
exitOnPluginFailure Boolean Enabling this flag will cause the service to exit when there is a problem loading a plugin. The old functionality is deprecated [D006], so enabling this feature is recommended.
enableScopedConfig Boolean Enabling this flag ensures that a plugin only receives the config relevant to that plugin. The old functionality is deprecated [D009], so enabling this feature is recommended.
enableNullModelFields Boolean Enable support for null fields coming from Models. The old functionality is deprecated [D013], so enabling this feature is recommended.
enableModelNameEncoding Boolean Enable support for model names being percent-encoded as per RFC-3986 in auto-generated API. The old functionality is deprecated [D012], so enabling this feature is recommended.
enableModelNameEncodingInSwagger Boolean Enable support for model names being percent-encoded as per RFC-3986 in API Builder's Swagger. The old functionality is deprecated [D014], so enabling this feature is recommended.
enableModelNameEncodingWithConnectorSlash Boolean Enable support for model names being encoded while preserving the connector's slash. The old functionality is deprecated [D015], so enabling this feature is recommended.
enableOverrideEndpointContentType
Boolean

Enable support for overriding endpoint content-type using the flow's HTTP response headers, and returning raw data from flows. The old functionality is deprecated [D042], so enabling this feature is recommended.

enableModelErrorOutputs
Boolean
Enable support for model flow-nodes having Error outputs. The old functionality is deprecated   [D043], so enabling this feature is recommended.

logLevel

[string] Sets the log level for the logger utility. Accepted values are (in order of most-verbose to least) trace, debug, info, warn, error, fatal, none.

session

[object] You can generally leave this as-is since it is generated for each new project you create. The session object may contain the following key-value pairs:

Key Type Default Description
encryptionAlgorithm String aes256 Encryption algorithm.
encryptionKey String - Encryption key.
signatureAlgorithm String sha512-drop256 Signature algorithm.
signatureKey String - Signature key.
secret String - Should be a large un-guessable string.
duration String 86400000 How long the session will stay valid in milliseconds.
activeDuration String 300000 The session will be extended by activeDuration milliseconds.

port

[number/string] The port to listen on for HTTP requests. Defaults to 8080. This key is deprecated [D038], use http.port instead.

http

[object] Your HTTP configuration goes here:

Key Type Description
port Number

The port to listen on for HTTP requests.

disabled Boolean

False by default. When this flag is set to True HTTP traffic is disabled.

For this to work, baseurl should point to https path and ssl must be configured and used.

ssl

[object] Your SSL configuration goes here. The options are the same as what is used by Node.js https.createServer() method.  A subset is as follows:

Key Type Description
port Number The port to listen on for HTTPS requests.

 

key String/Buffer/Array Private keys in PEM format. PEM allows the option of private keys being encrypted. Encrypted keys will be decrypted with  options.passphrase. Multiple keys using different algorithms can be provided either as an array of unencrypted key strings or buffers, or an array of objects in the form {pem: <string|buffer>[, passphrase: <string>]}. The object form can only occur in an array. object.passphrase is optional. Encrypted keys will be decrypted with object.passphrase if provided, or options.passphrase if it is not.
cert String/Buffer/Array Cert chains in PEM format. One cert chain should be provided per private key. Each cert chain should consist of the PEM formatted certificate for a provided private key, followed by the PEM formatted intermediate certificates (if any), in order, and not including the root CA (the root CA must be pre-known to the peer, see ca). When providing multiple cert chains, they do not have to be in the same order as their private keys in key. If the intermediate certificates are not provided, the peer will not be able to validate the certificate, and the handshake will fail.
passphrase string Encrypted keys will be decrypted with this if provided.

timeout

[number] The number of milliseconds before timing out a request to the server.

healthCheckAPI

[string] Path to a file that exports an express middleware function, which is used as a healthcheck. See Middleware callback function examples for more information on express middleware functions. 

This healthcheck middleware is executed by invoking GET /apibuilderPing.json. By default, invoking this endpoint will return { success: <bool> }, where <bool> is true as long as the service is not shutting down.

Example:

default.js
healthCheckAPI: '../healthCheck.js'
../healthCheck.js
module.exports = function (req, resp) {
	return resp.json({ success: 'Service is up' });
}

bindProcessHandlers

[boolean] True by default. When this is set to false, API Builder won't automatically shut down or restart on process signals such as SIGUSR2, SIGINT and SIGABRT, as well as on exit and uncaught exception events. bindProcessHandlers should be set to false when starting API Builder as part of another process (i.e. during mocha unit tests), otherwise any bound process handlers may interfere with the main process and cause unexpected behaviour.

Configuration files

API Builder will look for two sets of configuration files in the ./conf directory of the application, those ending in default.js and local.js. The default files are part of the source for your application, whereas the local files might contain sensitive information (such as passwords) and are not source controlled (these files will be ignored by the Git repository). At startup, all default files are loaded and sorted and merged into a single configuration object. Then, all local files are loaded, sorted, and merged with the single configuration object.

Usually, the values for configuration parameters are directly specified in the configuration file. However, for sensitive information, those values could be environmentalized. For how to do that, refer to the Environmentalization guide. The important thing to know is that if environmentalization is used, all the values will come as strings and might need subsequent type conversion like this:

default.js
module.exports = {
  // In this case we convert the string value that comes from the environment to integer. Similar approach would be with floats.
  timeout: parseInt(process.env.TIMEOUT, 10),
 
  // In this case we convert the string value to boolean
  printEnvVars: process.env.PRINT_ENV_VARS === "true"
}

Related Links