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.

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

Example configuration file:

./conf/default.js
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',

    // By default the authentication strategy is 'basic' which will use HTTP Basic Authorization where the
    // usename is the key and the password is blank.  The other option is 'apikey' where the value of the
    // APIKey header is the value of the key.  you can also set this to 'plugin' and define the key
    // 'APIKeyAuthPlugin' which points to a file or a module that implements the authentication strategy.
    // If you want to remove authentication then set this to 'none'.
    APIKeyAuthType: 'basic',

    // 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
    apiPrefix: '/api',

    // 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',
 
    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
    }
};

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 undefined Hostname and optional port which the server can be accessed on.
overrides.schemes array undefined Schemes which the server can be accessed using. Can be an array containing any of 'http', 'https', 'ws', or 'wss'
overrides.basePath string undefined The root path which the APIs hosted by the server are available on. 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.

APIKeyAuthPlugin

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

For details, see Authentication Schemes.

APIKeyAuthType

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

For details, see Authentication Schemes.

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.

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 all.

Access-Control-Allow-Credentials

Boolean Specified 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.

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.

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

Session will be extended by activeDuration milliseconds.

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