Deprecations

17 minute read

API Builder regularly adds feature improvements, fixes, and occasionally identify and fix features that do not work as designed, or are orthogonal to the intended direction of the product. When these are identified, we mark them as deprecated and add them to this document. We intend to remove all the deprecated features in the next major release of the product.

Direct or indirect use of deprecated features may result in a warning when the service starts. This should not affect the functionality of your service, but the flags should be an indication that, if ignored, your service may fall behind any future breaking changes and may increase the effort to upgrade to future major releases.

Deprecation flags

Where fixing a bug or introducing a feature would introduce a breaking change, we create a deprecation flag that is disabled by default, meaning that it will have no impact on your project. However, it should not be ignored. These flags are provided to allow you to manually review the change and be aware of a functional change that may also require code or config to be modified.

When addressing deprecation warnings with corresponding flags, you should compare the following set of flags with those located in your ./conf/default.js. The full set of flags is below for convenience. In upgraded applications, the flags will be disabled. However, newly created applications will have these flags enabled. For each deprecation warning, you should find the corresponding deprecation below, read the document, and understand how it applies to your application. To ensure that your application continues to operate as expected, it is essential that you have unit-tests for all your interfaces. Enabling a flag, without understanding or testing the impact can have adverse effects.

// ./conf/default.js

module.exports = {
	// Flags to enable features that are not ready for production or
	// whose use may require manual upgrade steps in legacy services.
	flags: { 
		// 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: false,
		// 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.
		usePrimaryKeyType: false,
		// Enabling this flag will cause the service to exit when there is a problem loading a plugin.
		exitOnPluginFailure: false,
		// 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: false,
		// Enable support for the $like comparison operator in the Memory connector.
		enableMemoryConnectorLike: false,
		// Enabling this flag ensures that a plugin only receives the config relevant to that plugin.
		enableScopedConfig: false,
		// 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: false,
		// Enable support for null fields coming from Models.
		enableNullModelFields: false,
		// 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: false,
		// 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: false,
		// Enable support for overriding endpoint content-type using the flow's HTTP response headers.
		enableOverrideEndpointContentType: false,
		// Enable support for model flow-nodes having Error outputs.
		enableModelErrorOutputs: false,
		// Enabling this flag will cause the service to exit when there is an error validating the service
		// Swagger or any loaded JSON schema.
		exitOnSwaggerSchemaValidationError: false,
		// Enabling this flag will emit the log level in each log message.
		enableLoggingOfLevel: false,
		// Enabling this flag will ignore HTTP payload body on GET and HEAD methods.
		enableStrictBodyPayloads: false,
		// Disables endpoints
		disableEndpoints: false,
	}
}

List of deprecated features

The following sections list the deprecated features.

[D001] /apidoc/docs.json

Swagger API docs are available on /apidoc/swagger.json and are mirrored on /apidoc/docs.json. Using the /apidoc/docs.json endpoint to access Swagger API documentation is deprecated and /apidoc/swagger.json should be used instead.

[D002] apiDocPrefix

Usage of admin.apiDocPrefix in the project configuration has been deprecated. Use apidoc.prefix instead. If both values are provided, apidoc.prefix will be preferred.

[D003] disableAPIDoc

Usage of admin.disableAPIDoc in the project configuration has been deprecated.

[D004] enableModelsWithNoPrimaryKey

For models that do not have a primary key:

• The delete, findAndModify, findByID, upsert, and update APIs and endpoints will not be generated.
• The Model flow-node will not have delete, findAndModify, findByID, upsert, or update methods.
• The Create API will no longer return a location header.

This will be the default behavior in all new services. For more information on how to be prepared for the change, and to start using the new behavior now, refer to Removal of unsupported APIs on Models that do not have a primary key.

[D005] usePrimaryKeyType

model IDs are based on the database’s primary key type instead of being hard-coded as a string.

This will be the default behavior in all new services. For more information on how to be prepared for the change, and to start using the new behavior now, refer to Removal of strings as default Model IDs.

[D006] exitOnPluginFailure

Errors when loading API Builder plugins will cause the service to terminate.

This will be the default behavior in all new services. For more information on how to be prepared for the change, and to start using the new behavior now, refer to Change in the loading of plugins when errors occur.

[D007] enableAliasesInCompositeOperators

Queries on Composite Models will support comparison operators ($eq, $ne, $in, $nin, $lt, $lte, $gt, $gte, $like) on aliased fields.

This will be the default behavior in all new services. For more information on how to be prepared for the change, and to start using the new behavior now, refer to Change in the handling of comparison operators on composite models.

[D008] enableMemoryConnectorLike

queries on models using the Memory connector that also use the $like comparison operator will search using the query parameter instead of just returning an empty array.

This will be the default behavior in all new services. For more information on how to be prepared for the change, and to start using the new behavior now, refer to Change in the handling of memory model queries using $like comparison operator.

[D009] enableScopedConfig

when loading an API Builder plugin, you will only receive the config relevant to the uploaded plugin.

This will be the default behavior in all new services. For more information on how to be prepared for the change, and to start using the new behavior now, refer to Change in the way config is passed to plugins.

[D010] perURLAuthentication

authentication has changed to make all paths secure, and public paths must be explicitly declared.

For more information on how to be prepared for the change, refer to Change in the way of handling authentication and authentication plugins.

[D011] API Builder Web

API Builder Web is deprecated and will be removed in a future major version. If you are currently using Web Routes, consider switching to another modern web application architecture for your front end that consumes API Builder APIs.

[D012] enableModelNameEncoding

model names are URI encoded as per RFC-3986, and the APIs that are auto-generated for models will bind to their URI equivalent.

This will be the default behavior in all new services. For more information on how to be prepared for the change, and to start using the new behavior now, refer to Change in the way model name is encoded in URI.

[D013] enableNullModelFields

Queries on models, which have fields with null values, can now return that field in the response rather than hiding the field. Support for this behavior is dependent on the connector being used.

This will be the default behavior in all new services. For more information on how to be prepared for the change, and to start using the new behavior now, refer to Change in the way null fields are returned in Models.

[D014] enableModelNameEncodingInSwagger

model names are URI encoded as per RFC-3986, and the APIs that are created from “Generate endpoints for models” will bind to their URI equivalent.

This will be the default behavior in all new services. For more information on how to be prepared for the change, and to start using the new behavior now, refer to Change in the way model name is encoded in Swagger.

[D015] enableModelNameEncodingWithConnectorSlash

model names which are prefixed with their connector name (in other words, oracle/user) will no longer have the slash encoded as %2F in auto-generated API paths.

This depends on D012.

This will be the default behavior in all new services. For more information on how to be prepared for the change, and to start using the new behavior now, refer to Change in the way model name with connector prefix is encoded in paths.

[D016] Model.define

Model.define is deprecated and will be removed in a future version of the product. Use Model.extend or APIBuilder.createModel instead.

[D017] Model instance reduce and APIBuilder.Model.reduce

Reducing a Model instance (i.e. Model.prototype.reduce) and APIBuilder.Model.reduce are deprecated and will be removed in a future version of the product.

For more information on how to be prepared for the change, refer to Removal of the Model instance reduce and APIBuilder.Model.reduce functions.

[D018] APIBuilder.removeModel

APIBuilder.removeModel is deprecated and will be removed in a future version of the product.

[D019] APIBuilder.removeConnector

APIBuilder.removeConnector is deprecated and will be removed in a future version of the product.

[D020] APIBuilder.removeBlock

APIBuilder.removeBlock is deprecated and will be removed in a future version of the product.

[D021] APIBuilder.removeAPI

APIBuilder.removeAPI is deprecated and will be removed in a future version of the product.

[D022] APIBuilder.removeAPIByFilename

APIBuilder.removeAPIByFilename is deprecated and will be removed in a future version of the product.

[D023] APIBuilder.removeRoute

APIBuilder.removeRoute is deprecated and will be removed in a future version of the product.

[D024] Model prefix

Creating a Model with the prefix property is deprecated and will be removed in a future version of the product.

For more information on how to be prepared for the change, refer to Removal of Model prefix.

[D025] Model.prototype.extend

Extending a model instance (i.e. Model.prototype.extend) is deprecated and will be removed in a future version of the product. Use Model.extend instead.

[D026] APIBuilder.app.locals

APIBuilder.app.locals properties appc_external_url, appc_external_apidoc_path_legacy, appc_external_apidoc_path, or appc_external_apidoc_url are deprecated and will be removed in a future version of the product.

[D027] APIBuilder.debug

APIBuilder.debug is deprecated and will be removed in a future version of the product.

[D028] Codeblocks

codeblocks are deprecated and will be removed in a future version of the product.

For more information on how to be prepared for the change, refer to Removal of codeblocks.

[D029] @axway/api-builder-react-engine

@axway/api-builder-react-engine is deprecated and will not receive any updates. If you are currently using Web Routes, consider switching to another modern web application architecture for your front end that consumes API Builder Service APIs.

[D030] APIBuilder.get

APIBuilder.get is deprecated and will be removed in a future version of the product.

[D031] APIBuilder.pluralize

APIBuilder.pluralize is deprecated and will be removed in a future version of the product. Use the pluralize module instead.

[D032] APIBuilder.singularize

APIBuilder.singularize is deprecated and will be removed in a future version of the product. Use the pluralize module instead.

[D033] APIBuilder.logger.stripColors

APIBuilder.logger.stripColors is deprecated and will be removed in a future version of the product.

[D034] Model.fields[name].optional and API.parameters[name].optional

Using the optional property on Model fields and API parameters is deprecated and will be ignored in a future version of the product. Use the required property instead.

[D035] Logger.createDefaultLogger

The static function Logger.createDefaultLogger is deprecated and will be removed in a future version of the product.

[D036] Logger.createRestifyLogger

The static function Logger.createRestifyLogger is deprecated and will be removed in a future version of the product.

[D037] Sort

Creating an API or Route with the sort property is deprecated in favor of a more robust internal sort mechanism.

[D038] Port

Usage of port in the project configuration has been deprecated. Use http.port instead.

[D039] Unmaintained Node.js versions

We introduced a Node.js support policy in which end-of-life Node.js versions are automatically deprecated by API Builder. See https://nodejs.org/en/about/releases for the versions which are actively maintained. While the versions we deem as deprecated are not recommended, API compatibility will be maintained until an explicit breaking change removes it. Only use Active LTS or Maintenance LTS Node.js versions in production.

[D040] Node.js v10

Node.js v10 has been deprecated. See API Builder’s Node.js support policy. While the versions we deem as deprecated are not recommended, API compatibility will be maintained until an explicit breaking change removes it. Only use Active LTS or Maintenance LTS Node.js versions in production.

[D041] logger.logRequest and logger.logResponse

The logRequest and logResponse functions on the API Builder logger are deprecated and will be removed in a future version of the product.

[D042] enableOverrideEndpointContentType

API Endpoints will no longer return the Content-Type application/json in all cases, the Content-Type will either be explicitly set from within a flow, or set according to the type of response body.

This will be the default behavior in all new services. For more information on how to be prepared for the change, and to start using the new behavior now, refer to Change in the way Endpoints return Content-Type.

[D043] enableModelErrorOutputs

Model flow-nodes will gain an additional output, Error. This will be the default behavior when flows are generated from models in all new services.

This will be the default behavior in all new services. For more information on how to be prepared for the change, and to start using the new behavior now, refer to Change in the outputs of Model flow-nodes.

[D044] API.response

The response property on the custom API is deprecated in favor of the model property. The model property serves the same purpose in that the named model is used to describe the response schema in the generated API Swagger documentation.

[D045] exitOnSwaggerSchemaValidationError

Validation errors when loading JSON schemas will cause the service to terminate. Additionally, the service’s Swagger API docs are now validated and will cause the service to terminate if found to be invalid.

This will be the default behavior in all new services. For more information on how to be prepared for the change, and to start using the new behavior now, refer to Addition of Swagger and json schema validation on start.

[D046] config.bodyParser

The bodyParser config option is deprecated and will be removed in a future version of the product.

[D047] config.busboy

The busboy config option is deprecated and will be removed in a future version of the product. Use config.limits to configure limits for multipart/form-data requests and return 413 to clients when a limit it hit.

[D048] undefinedMultipartPartSize

The new config.limits config option should be configured with a value. Leaving it unset is deprecated behavior and the default behavior will change in a future version of the product to be equivalent to setting infinity (no limit).

[D049] enableLoggingOfLevel

each log message will display it’s log level (e.g. INFO).

This will be the default behavior in all new services. For more information on how to be prepared for the change, and to start using the new behavior now, refer to Change in log message format for levels.

[D050] enableStrictBodyPayloads

HTTP methods GET and HEAD will ignore payload body. Enabling this flag is recommended for security purposes.

This will be the default behavior in all new services. For more information on how to be prepared for the change, and to start using the new behavior now, refer to Change in the way body is handled for HTTP methods GET and HEAD.

[D051] disableServerBanner

The disableServerBanner config option has been deprecated in favor of http.headers.server.

[D052] runtimePeerDependency

Using dependencies with a peerDependency on @axway/api-builder-runtime has been deprecated and may cause issues when using npm 7 or higher.

For more information on how to be prepared for the change, refer to Change in the way plugins document API Builder compatibility.

[D053] disableEndpoints

Endpoints are deprecated and have been replaced with the OpenAPI flow-trigger. Follow this guide to replace endpoints in your service.

[D054] apidoc.disabled

Usage of apidoc.disabled to stop OpenAPI documentation being accessible has been deprecated and should not be used.

[D055] Node.js v14

Node.js v14 has been deprecated. API compatibility will be maintained until API Builder v5. See API Builder’s Node.js support policy.

[D056] disableLegacyHeaders

Automatically sending HTTP response headers “server”, “content-md5”, and “etag” are deprecated and will no longer be sent unless explicitly enabled in http.headers configuration.

For more information on how to be prepared for the change, refer to Change in default behavior for HTTP response headers.