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 object are auto-generated when you create a new project.

Example configuration file:

./conf/default.js  Expand source
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: 'bu+WKZpJ7m5H73xr+Fr/Xz4LVbFgLSoW',
	// This is the base url the service will be reachable at not including the port
	baseurl: 'http://localhost',
	// This is the port the service will be bound to
	port: 8080,
	// Enabling this property will print out the process.env at startup time
	printEnvVars: false,
	// Your ssl configuration goes here. The options are the same has what is used by
	// Node.js https.createServer() method
	// https://nodejs.org/api/https.html#https_https_createserver_options_requestlistener
	// ssl: {
	// 	port: 8443
	// },
	// The number of milliseconds before timing out a request to the server.
	timeout: 120000,
	// Log level of the main logger. Can be set to 'debug', 'error', 'fatal', 'info', 'trace', or 'warn'.
	logLevel: 'debug',
	// 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: []
	},
	// Control 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'
		]
	},
	// Controls for swagger API Documentation
	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',
		// Overrides to make to the swagger API documentation.
		// This will not change how the server is hosted  - use apiPrefix, port and ssl configuration instead
		// This is useful when the service is not consumed directly, such as through a proxy
		overrides: {
			// The transfer protocol of the service. Values MUST be one or more of 'http', 'https', 'ws' or 'wss'
			// schemes: [ 'https' ],
			// 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.
			// host: 'localhost:8080',
			// 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 no basePath
			// basePath: '/'
		}
	},
	// You can generally leave this as-is since it is generated for each new service you created.
	session: {
		encryptionAlgorithm: 'aes256',
		encryptionKey: 'cfL+oLlnhMsu3MuQp2/ecBRyDyfBuQTUAynrexMIEMg=',
		signatureAlgorithm: 'sha512-drop256',
		signatureKey: 'UVYA9hxakKdQ170JovEYNYxKgtA0NmMwwj2g9YGjqItHcW5rrNahdaoZICd/UJ3+UsHVSvqWZCU5Q9OA3UTaZg==',
		secret: 'Gyikhw4/Yw4DQeA1XKYQY36lOW7dUf0J', // should be a large unguessable string
		duration: 86400000, // how long the session will stay valid in ms
		activeDuration: 300000 // if expiresIn < activeDuration, the session will be extended by activeDuration milliseconds
	},
	// If you want signed cookies, you can set this value. if you don't want signed cookies, remove or make null
	cookieSecret: 'WSq1ebvekzR5BYjyNWR2m2Cjb+gnbQfO',
	// your connector configuration goes here
	connectors: {
	},
	// Cross-Origin Resource Sharing settings
	cors: {
		// List of allowed origins (format: any, space separated string, array or regex)
		// 'Access-Control-Allow-Origin': '*' or 'http://foo.com http://bar.com' or ['http://foo.com', 'http://bar.com'] or /foo\.com$/,
		// Sets the Access-Control-Allow-Credentials header on API responses. Can be true or false
		// 'Access-Control-Allow-Credentials': false,
		// Only these methods will be allowed out of all available 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-Methods': ['GET', 'PUT', 'POST', 'PATCH', 'DELETE'],
		// 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'],
		// 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']
	},
	// The path to a file which exports an express middleware function used as a healthcheck.
	// See `https://expressjs.com/en/4x/api.html#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.
	// healthCheckAPI: './healthCheck.js',
	// This configuration option allows to configure proxy server URL that can be leveraged in plugins that do http/s communication
	// proxy: 'http://localhost:8081',
	flags: {
		// Flags to enable features that are not ready for production or
		// whose use may require manual upgrade steps in legacy services.
		// 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 aliasesd 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 model names being percent-encoded as per RFC-3986.
		// Breaking change for old versions as previously names like "foo/bar" will now be encoded as "foo%2Fbar"
		enableModelNameEncoding: true,
		// Enable support for null fields coming from Models
		enableNullModelFields: true
	},
	authorization: {
		callback: '/auth/callback',
		credentials: {
		}
	}
};
  

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. Prefix for the API documentation.

disableAPIDoc Boolean false Deprecated. 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] Prefix path to use for the API requests for Models and APIs. Each endpoint you define in a Model or API will be prefixed by this value. The provided value must start with a leading slash (/). By default, it is set to /api. Authenticated access to these endpoints is controlled via accessControl.

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. In addition, 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, 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, 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 their own 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, 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, 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, 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, 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, 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, so enabling this feature is recommended.

enableModelNameEncoding

Boolean Enable support for model names being percent-encoded as per RFC-3986. The old functionality is deprecated, so enabling this feature is recommended.

enableNullModelFields

Boolean Enable support for null fields coming from Models. The old functionality is deprecated, so enabling this feature is recommended.

logLevel

[string] Sets the log level for the logger utility. Accepted values are debugerrorfatalinfotrace, or warn.

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.

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 Host server port.

 

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 which 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' });
}

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.

Related Links