API Builder Deprecations

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.

Icon

To ensure that you stay abreast of important updates and to make it easier to upgrade, you should pay attention to the deprecation warnings and address them as soon as possible.

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 are disabled by default.  However, newly created applications will have these flags enabled.  For each deprecation warning, you should find the corresponding feature flag 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: {
		// 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 aliased fields.
		enableAliasesInCompositeOperators: false,
		// Enable support for the $like comparison operator in the Memory connector.
		enableMemoryConnectorLike: false,
		// 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 user 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,
		// Enabling this flag ensures that a plugin only receives the config relevant to that plugin.
		enableScopedConfig: false,
		// Enable support for null fields coming from Models
		enableNullModelFields: 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 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
	}
};

List of Deprecated features

The following sections list the deprecated features.

[D001] /apidoc/docs.json

Beginning with the 4.0.0 release, 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

Beginning with the Boston release, 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. See Project Configuration.

[D003] disableAPIDoc

Beginning with the Boston release, Usage of admin.disableAPIDoc in the project configuration has been deprecated. Use apidoc.disabled instead. If both values are provided, apidoc.disabled will be preferred. See Project Configuration.

[D004] enableModelsWithNoPrimaryKey

Beginning with the Canberra release, For Models that do not have a primary key:

  • The deletefindAndModifyfindByIDupsert, and update APIs and endpoints will not be generated.
  • The Model flow-node will not have deletefindAndModifyfindByIDupsert, 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

Beginning with the Canberra release, 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

Beginning with the Dublin release, 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

Beginning with the Eden release, 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

Beginning with the Eden release, 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

Beginning with the Istanbul release, 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

Beginning with the Lisbon release, Authentication has changed to make all paths secure, and public paths must be explicitly declared. 

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 of handling authentication and authentication plugins.

[D011] API Builder Web

Beginning with the Lisbon release, 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 Service APIs.

[D012] enableModelNameEncoding

Beginning with the Osaka release, 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

Beginning with the Quebec release, 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

Beginning with the Quebec release, 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

Beginning with the Barcelona release, 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 flag 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

Beginning with the Cairo release, 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

Beginning with the Cairo release, 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

Beginning with the Cairo release, APIBuilder.removeModel is deprecated and will be removed in a future version of the product.

[D019] APIBuilder.removeConnector

Beginning with the Cairo release, APIBuilder.removeConnector is deprecated and will be removed in a future version of the product.

[D020] APIBuilder.removeBlock

Beginning with the Cairo release, APIBuilder.removeBlock is deprecated and will be removed in a future version of the product.

[D021] APIBuilder.removeAPI

Beginning with the Cairo release, APIBuilder.removeAPI is deprecated and will be removed in a future version of the product.

[D022] APIBuilder.removeAPIByFilename

Beginning with the Cairo release, APIBuilder.removeAPIByFilename is deprecated and will be removed in a future version of the product.

[D023] APIBuilder.removeRoute

Beginning with the Cairo release, APIBuilder.removeRoute is deprecated and will be removed in a future version of the product.

[D024] Model prefix

Beginning with the Cairo release, Creating a Model with the prefix property is deprecated and will be removed in a future version of the product. See Removal of Model prefix.

[D025] Model.prototype.extend

Beginning with the Cairo release, 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

Beginning with the Cairo release, 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

Beginning with the Cairo release, APIBuilder.debug is deprecated and will be removed in a future version of the product.

[D028] Codeblocks

Beginning with the Cairo release, 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

Beginning with the Cairo release, @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

Beginning with the Cairo release, APIBuilder.get is deprecated and will be removed in a future version of the product.

[D031] APIBuilder.pluralize

Beginning with the Cairo release, APIBuilder.pluralize is deprecated and will be removed in a future version of the product. Use the pluralize module instead.

[D032] APIBuilder.singularize

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

[D033] APIBuilder.logger.stripColors

Beginning with the Cairo release, 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

Beginning with the Cairo release, 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

Beginning with the Cairo release, The static function Logger.createDefaultLogger is deprecated and will be removed in a future version of the product.

[D036] Logger.createRestifyLogger

Beginning with the Cairo release, The static function Logger.createRestifyLogger is deprecated and will be removed in a future version of the product.

Related Links