Project configuration

12 minute read

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.

Configuration files

API Builder will look for two types of configuration files in the ./conf directory of the application, either “default” or “local”, for example:

• default.js
• local.js
• oracle.default.js
• oracle.local.js

Files ending in default.js are part of the application, can be added to source control, and will be released into production, so these must never contain sensitive information, such as passwords.

Files ending in local.js are never be added to source control, and will not be released into production, so these files can contain sensitive information such as passwords. These are explicitly ignored in .gitignore and .dockerignore. If you use alternate source control or deployment methods, then you should ensure that these files are not deployed.

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, and can override the “default” configuration.

Usually, the values for configuration parameters are specified directly in the configuration file. However, for sensitive information, those values could be environmentalized (see the Environmentalization guide for more information). The important thing to know about environmentalized parameters is that all the values are provided to the application 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"
}

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:

apidoc

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

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, a model “user” would have its API bound to /api/user.

The apiPrefix is an important consideration when you are designing the interface for your service with OpenAPI as part of the API-first design process. See Writing OpenAPI documents for more information.

limits

[object] Configures request limits for the API Builder server.

accessControl

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

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 do not 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:

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.

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:

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:

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:

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: '../healthcheckapi.js'

// ../healthcheckapi.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 will not 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.