API Builder 4.x Save PDF Selected topic Selected topic and subtopics All content Project configuration 11 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. Note API key values and session objects are auto-generated when you create a new project. 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 OpenAPI 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 OpenAPI documentation since the API Builder Standalone - Boston release. The apidoc object may contain the following key-value pairs: Key Type Default Description 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 - OpenAPI 2 specific override. Hostname and optional port on which the server can be accessed. The value can be set to null to clear the host. overrides.schemes array - OpenAPI 2 specific override. Schemes which the server can be accessed using. Can be an array containing any of http, https, ws, or wss. The value can be set to null to clear the schemes. overrides.basePath string - OpenAPI 2 specific override. 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. overrides.servers array - OpenAPI 3 specific override. If provided, this must be an array of server objects, and each server must contain the server url as string. The value can be set to null to clear the servers. 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. Key Type Default Description multipartPartSize number string Infinity 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 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: 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 enableModelsWithNoPrimaryKey Boolean 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. The old functionality is deprecated [D004], so enabling this feature is recommended. usePrimaryKeyType Boolean Generate APIs and flows that use primary key type rather than always assuming string. Breaking change for old versions as the generated APIs will change when 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. enableAliasesInCompositeOperators Boolean 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. The old functionality is deprecated [D007], so enabling this feature is recommended. enableMemoryConnectorLike Boolean Enable support for the $like comparison operator in the Memory connector. The old functionality is deprecated [D008], 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. enableModelNameEncoding Boolean 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". The old functionality is deprecated [D012], 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. enableModelNameEncodingInSwagger Boolean 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". The old functionality is deprecated [D014], so enabling this feature is recommended. enableModelNameEncodingWithConnectorSlash Boolean 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". 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. 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. exitOnSwaggerSchemaValidationError Boolean Enabling this flag will cause the service to exit when there is an error validating the service Swagger or any loaded JSON schema. The old functionality is deprecated [D045], so enabling this feature is recommended. enableLoggingOfLevel Boolean Enabling this flag will emit the log level in each log message. The old functionality is deprecated [D049], so enabling this feature is recommended. enableStrictBodyPayloads Boolean Enabling this flag will ignore HTTP payload body on GET and HEAD methods. The old functionality is deprecated [D050], so enabling this feature is recommended. disableEndpoints Boolean Disables endpoints The old functionality is deprecated [D053], 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. headers.etag Boolean True by default. Enabling will send an ‘etag’ response header which contains a unique key for aspecific version of a resource. headers[‘content-md5’] Boolean True by default. Enabling will send a ‘content-md5’ response header which contains an MD5 hash of the response body. headers.server Boolean True by default. Enabling will send a ‘server’ response header which describes the server. i.e. server: API Builder/4.67.6 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 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: '../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. 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" } Last modified April 22, 2022: london release notes (#77) (e05b494) Related Links
Project configuration 11 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. Note API key values and session objects are auto-generated when you create a new project. 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 OpenAPI 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 OpenAPI documentation since the API Builder Standalone - Boston release. The apidoc object may contain the following key-value pairs: Key Type Default Description 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 - OpenAPI 2 specific override. Hostname and optional port on which the server can be accessed. The value can be set to null to clear the host. overrides.schemes array - OpenAPI 2 specific override. Schemes which the server can be accessed using. Can be an array containing any of http, https, ws, or wss. The value can be set to null to clear the schemes. overrides.basePath string - OpenAPI 2 specific override. 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. overrides.servers array - OpenAPI 3 specific override. If provided, this must be an array of server objects, and each server must contain the server url as string. The value can be set to null to clear the servers. 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. Key Type Default Description multipartPartSize number string Infinity 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 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: 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 enableModelsWithNoPrimaryKey Boolean 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. The old functionality is deprecated [D004], so enabling this feature is recommended. usePrimaryKeyType Boolean Generate APIs and flows that use primary key type rather than always assuming string. Breaking change for old versions as the generated APIs will change when 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. enableAliasesInCompositeOperators Boolean 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. The old functionality is deprecated [D007], so enabling this feature is recommended. enableMemoryConnectorLike Boolean Enable support for the $like comparison operator in the Memory connector. The old functionality is deprecated [D008], 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. enableModelNameEncoding Boolean 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". The old functionality is deprecated [D012], 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. enableModelNameEncodingInSwagger Boolean 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". The old functionality is deprecated [D014], so enabling this feature is recommended. enableModelNameEncodingWithConnectorSlash Boolean 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". 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. 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. exitOnSwaggerSchemaValidationError Boolean Enabling this flag will cause the service to exit when there is an error validating the service Swagger or any loaded JSON schema. The old functionality is deprecated [D045], so enabling this feature is recommended. enableLoggingOfLevel Boolean Enabling this flag will emit the log level in each log message. The old functionality is deprecated [D049], so enabling this feature is recommended. enableStrictBodyPayloads Boolean Enabling this flag will ignore HTTP payload body on GET and HEAD methods. The old functionality is deprecated [D050], so enabling this feature is recommended. disableEndpoints Boolean Disables endpoints The old functionality is deprecated [D053], 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. headers.etag Boolean True by default. Enabling will send an ‘etag’ response header which contains a unique key for aspecific version of a resource. headers[‘content-md5’] Boolean True by default. Enabling will send a ‘content-md5’ response header which contains an MD5 hash of the response body. headers.server Boolean True by default. Enabling will send a ‘server’ response header which describes the server. i.e. server: API Builder/4.67.6 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 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: '../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. 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" } Last modified April 22, 2022: london release notes (#77) (e05b494)
Project configuration 11 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. Note API key values and session objects are auto-generated when you create a new project. 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 OpenAPI 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 OpenAPI documentation since the API Builder Standalone - Boston release. The apidoc object may contain the following key-value pairs: Key Type Default Description 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 - OpenAPI 2 specific override. Hostname and optional port on which the server can be accessed. The value can be set to null to clear the host. overrides.schemes array - OpenAPI 2 specific override. Schemes which the server can be accessed using. Can be an array containing any of http, https, ws, or wss. The value can be set to null to clear the schemes. overrides.basePath string - OpenAPI 2 specific override. 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. overrides.servers array - OpenAPI 3 specific override. If provided, this must be an array of server objects, and each server must contain the server url as string. The value can be set to null to clear the servers. 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. Key Type Default Description multipartPartSize number string Infinity 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 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: 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 enableModelsWithNoPrimaryKey Boolean 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. The old functionality is deprecated [D004], so enabling this feature is recommended. usePrimaryKeyType Boolean Generate APIs and flows that use primary key type rather than always assuming string. Breaking change for old versions as the generated APIs will change when 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. enableAliasesInCompositeOperators Boolean 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. The old functionality is deprecated [D007], so enabling this feature is recommended. enableMemoryConnectorLike Boolean Enable support for the $like comparison operator in the Memory connector. The old functionality is deprecated [D008], 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. enableModelNameEncoding Boolean 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". The old functionality is deprecated [D012], 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. enableModelNameEncodingInSwagger Boolean 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". The old functionality is deprecated [D014], so enabling this feature is recommended. enableModelNameEncodingWithConnectorSlash Boolean 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". 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. 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. exitOnSwaggerSchemaValidationError Boolean Enabling this flag will cause the service to exit when there is an error validating the service Swagger or any loaded JSON schema. The old functionality is deprecated [D045], so enabling this feature is recommended. enableLoggingOfLevel Boolean Enabling this flag will emit the log level in each log message. The old functionality is deprecated [D049], so enabling this feature is recommended. enableStrictBodyPayloads Boolean Enabling this flag will ignore HTTP payload body on GET and HEAD methods. The old functionality is deprecated [D050], so enabling this feature is recommended. disableEndpoints Boolean Disables endpoints The old functionality is deprecated [D053], 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. headers.etag Boolean True by default. Enabling will send an ‘etag’ response header which contains a unique key for aspecific version of a resource. headers[‘content-md5’] Boolean True by default. Enabling will send a ‘content-md5’ response header which contains an MD5 hash of the response body. headers.server Boolean True by default. Enabling will send a ‘server’ response header which describes the server. i.e. server: API Builder/4.67.6 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 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: '../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. 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" } Last modified April 22, 2022: london release notes (#77) (e05b494)