What's new for this release

IBM® API Connect Version 5.0, and later releases, delivers new function over the IBM API Management Version 4.0 release.

IBM API Connect provides a set of API capabilities that can be deployed on premises in your data center or on IBM Cloud. You can use IBM API Connect for defining, proxying, assembling, securing, and scaling APIs. IBM API Connect also provides detailed analytics and operational metrics. Use your company developer portal to provide links to social communities and manage applications that can be used by developers.

The IBM API Connect solution provides an intuitive user experience for managing the complete API lifecycle. From adding, publishing, and adopting APIs, to supporting, monitoring, and testing, IBM API Connect helps each company to realize the maximum value from their APIs.

IBM API Connect Version 5.0.0, and later releases, includes the following enhancements, release by release.

[V5.0.8 or later]

Version 5.0.8

Migrate your Developer Portal OVAs from Ubuntu V16.04 to Ubuntu V18.04
From API Connect Version 5.0.8.10 iFix 1, it is strongly recommended that you migrate your Developer Portal OVAs from Ubuntu V16.04 to Ubuntu V18.04, because support for Ubuntu V16.04 is being withdrawn in March 2021. For more information, see Migrating your Developer Portal OVAs from Ubuntu V16.04 to Ubuntu V18.04.
Change to the way in which the sending of client ID and scope to a third party OAuth provider is controlled
From API Connect Version 5.0.8.10, a new suppress-parameter header enables you to suppress the sending of client ID and scope to a third party OAuth provider; by default these parameters are now sent. For more information, see OAuth introspection for third-party OAuth providers
Detect illegal XML characters in API request headers
From API Connect Version 5.0.8.10, a new x-ibm-gateway-inspect-request-headers API property enables the inspection of the HTTP headers in the API request to check for characters in the header values that are illegal XML characters. By default, there is no inspection, and such characters cause the API request to fail with an HTTP 500 Internal Server Error, but with this property you can choose to replace these characters with ?, or to have the API request fail with an HTTP 400 Bad Request if any such characters are found. For more information, see API properties.
Badgerfish support for handling of empty XML elements by the map policy
From API Connect Version 5.0.8.10, the x-ibm-gateway-map-xml-empty-element API property provides new options that enable empty XML input element values to be placed into JSON badgerfish value properties. For more information, see API properties.
Control whether client ID and scope are sent to a third party OAuth provider
From API Connect Version 5.0.8.8, a new allowed-parameters header enables you to control whether API Connect client ID and scope are sent to the third party OAuth provider. For more information, see OAuth introspection for third-party OAuth providers.
Access the caught exception in a catch block
From API Connect Version 5.0.8.8, a new getError() function enables you to obtain the details of the current caught exception in the catch block of an API assembly. A possible use would be to create a custom error response using the details of the caught exception. For more information, see GatewayScript code examples.
Set the maximum number of concurrent Gateway server additions
From API Connect Version 5.0.8.8, you can set a limit on the maximum number of Gateway servers that can be added to a Gateway service concurrently. In particular, this reduces the time taken to refresh Gateway servers after an upgrade. For more information, see Setting the maximum number of concurrent Gateway server additions.
Remove a Gateway server from a Gateway service
From API Connect Version 5.0.8.8, you can remove a Gateway server from a Gateway service whilst retaining it in your API Connect cloud. You can then easily re-add it a Gateway service in the future if required. For more information, see Removing and deleting servers.
Emulate the behavior of IBM API Management Version 4.0 when handling backend server errors
From API Connect Version 5.0.8.8, a new x-ibm-gateway-invoke-emulate-v4-invoke-error property is provided for emulating the IBM API Management Version 4.0 behavior when handling SOAP faults or JSON errors from a back end server, whereby a DataPower error is initiated. This property supersedes x-ibm-gateway-invoke-emulate-v4-soap-error, which is deprecated. For more information, see API properties.
Enable post processing of mapped JSON output from the Map policy
From API Connect Version 5.0.8.8, a new ibm-gateway-map-post-process-json-output API property allows you to enable the post processing of JSON output to ensure that property values are of the same data type as that defined in the schema, and that output property values that have a Badgerfish JSON syntax, due to object mapping of an XML input, are normalized. For more information, see API properties.
(5.0.8.7 iFix 4 or later) Add new certificates to your DataPower® Gateway servers.
You must complete this task once before upgrading to API Connect 5.0.8.7 iFix 4 (or later), to prevent the loss of analytics events data during the upgrade. For instructions, see Add certificates to gateways before upgrading API Connect.

If you skip this task, the upgrade will be successful but you will lose analytics event records spanning the time when the management servers start up at the upgraded level until each Gateway server is removed and re-added after the upgrade.

Attention: This is a one-time task and does not need to be repeated with subsequent upgrades.
Allow JSON payload to be accepted without parsing errors
From Version 5.0.8.7 iFix3, if an API request or response payload includes valid JSON content that contains characters that cannot be represented in the JSONX XML internal syntax that is used by the DataPower Gateway, set the x-ibm-gateway-api-json-parse-error-handling property to escape-unicode to allow the payload to be accepted without parsing errors. For more information, see API properties.
Specify which SOAP port to use when importing a WSDL service
From API Connect Version 5.0.8.7, the WSDL import options file has a port field to specify which SOAP port to use in the WSDL definition when creating an API by importing a WSDL service. For more information, see Using an options file when importing a WSDL service.
New option in the Map policy for setting input data log message severity
From API Connect Version 5.0.8.7, the Map policy has a new Severity level for input data log messages option to set the severity level of generated error messages that relate to input data. For more information, see Configuring the Map policy in the user interface.
New API property for the Map policy to control the generation of default values for required properties
From API Connect Version 5.0.8.7, an x-ibm-gateway-map-emulate-v4-default-required-properties API property is available for use with the Map policy that, when set to true, generates default values in the output for required properties that are either not mapped, or for which there is no input data present, in the following specific cases:
  • An array consists of objects that contain one or more required properties.
  • An object which is optional has one or more child properties that are required.

For full details, see API properties.

Removal of some commands from the developer toolkit CLI
From API Connect Version 5.0.8.7, the following commands are no longer supported in the developer toolkit CLI:
apic start
apic stop
apic services
apic props
apic microgateway
apic swiftserver
Include an options file when importing a WSDL service
From API Connect Version 5.0.8.6, when you create an API definition, or add a target WSDL service to an API definition, by importing a .zip file, you can specify additional directives by including an options file in the .zip file. For more information, see Using an options file when importing a WSDL service.
Micro Gateway is deprecated in favor of DataPower Gateway
IBM API Connect Micro Gateway is deprecated in IBM API Connect Version 5.0.8 in favor of DataPower Gateway. From 1 April 2020, Micro Gateway, and associated toolkit CLI commands, will no longer be supported. Existing users can migrate their API definitions to IBM DataPower Gateways. For information on supported API policies, see Built-in policies.
Export the Management server configuration database in JSON format
From API Connect Version 5.0.8.5, a new config dbextract command is provided that exports the contents of the Management server configuration database in JSON format, in a .tar file. See Configuration commands.
Show and reset failed Developer Portal login attempts
From API Connect Version 5.0.8.5, you can run the reset_locked_host command to show you the IP addresses of all the clients that have made failed login attempts, on a per site basis. You can then clear the failed login attempts from specific or all IP addresses. See reset_locked_host and Flood control.
Additional JWT cryptographic algorithms
From API Connect Version 5.0.8.5, the Generate JWT policy supports the following additional cryptographic algorithms:
  • PS256
  • PS384
  • PS512
See Generate JWT.
New API properties
From API Connect Version 5.0.8.5, the following new API properties are available:
  • x-ibm-gateway-invoke-keep-payload: If set to true, the invoke policy sends a payload on an HTTP DELETE method.
  • x-ibm-gateway-map-resolve-xmlinput-datatypes: If set to false, XML input elements are always mapped as a string. If you set to a value of true, numeric or boolean XML input elements are mapped as the corresponding data type from the input schema.
  • x-ibm-gateway-map-xml-empty-element: Controls how the map policy handles XML input empty elements and impacts JSON output when the input document is XML.
  • x-ibm-gateway-sourcecode-resolve-apic-variables: If set to true, API Connect variable references are resolved.
  • x-ibm-gateway-schema-definition-reference-limit: Specifies the maximum allowed number of iterations of a circular schema definition.
See API properties.
Ability to disable automatic refresh of your Gateway servers after a gateway extension update
From API Connect Version 5.0.8.4, it is now possible to disable automatic refresh of gateway servers after a gateway extension update. Previous behavior was that an automatic refresh was performed after a gateway extension update. There is now an option under Gateway service settings called Automatically refresh extension on gateway servers. If you disable this option, then you can manually refresh the servers in the Gateway service rather than having the servers refreshed automatically. A manual refresh allows you to determine the timing and sequence of the updates in order to coordinate the activity with an external load balancer. Additionally, a manual refresh provides you with more control over potential downtime of API runtime traffic on gateway servers. See Configuring your Gateway server extensions.
Map input properties with null values
From API Connect Version 5.0.8.4, there is a new x-ibm-gateway-map-null-value API property for the map policy; setting the value of this property to true allows an input property with a value of null to be mapped to the output document. By default, an input property with a value of null is not mapped to the output document. See API properties.
Populate context variables for access by GatewayScript
From API Connect Version 5.0.8.4, there is a new x-ibm-gateway-custom-policy-with-gws-action property. If set to true, the request.body and message.body context variables will be populated for access by an apim.getvariable('request.body') or apim.getvariable('message.body') function call in a GatewayScript action of a custom policy. See API properties.
New error cases are supported by the assembly catch construct
From API Connect Version 5.0.8.3, the following new error cases are supported by the catch construct in an API assembly: BadRequestError, UnauthorizedError, and ForbiddenError. See Error cases supported by assembly catches.
Added the ability to remove analytics event fields from being collected to reduce storage requirements
From API Connect Version 5.0.8.3, you can reduce storage requirements by removing analytics event fields that you do not need to track. See Customizing the retained event record fields, Specifying the cloud settings, and API event record fields for more information.
Updated the query list and results for the detailed health check API to check for cloud dissociation
From API Connect Version 5.0.8.3, the failIfCloudIsDissociated parameter was added to make it easier to detect a cloud dissociation state by running the health check API. See Obtain health check data of Management servers by using REST API calls and Dissociation and your cloud for more information.
Added the useBytesSent query parameter to selected APIs
From API Connect Version 5.0.8.3, the useBytesSent parameter was added that allows the analytics field bytes_sent to be used to calculate the usage. See Return data usage information for all the resources used by a given application, Return data usage information for all the resources used by all applications in the given organization, Return combined data usage for all resources used by a given application, and Return combined data usage information for all the resources used by a given organization for more information.
Added the stat show apiconfig command to check the health of your Management server
From API Connect Version 5.0.8.3, the stat show apiconfig command returns information about your Management server. You can use this command to determine if your database is in good health before an upgrade, or run it regularly to ensure that your Management server is running correctly. See Testing Management servers for more information.
New isolate mode added to the config load apiconfig command for restoring your API Connect configuration
From API Connect Version 5.0.8.3 onwards, you can restore a previous version of your API Connect configuration in isolation mode. By using the isolate option on the config load apiconfig command, the management configuration file is loaded in isolation, in other words without any references to DataPower Gateway servers, Developer Portal servers, or any third-party systems for analytics offload. For more information, see Restoring an API Connect configuration.
You can encode + characters in the query parameter values of the target URL of an Invoke or Proxy policy
From API Connect Version 5.0.8.3, there is a new x-ibm-gateway-queryparam-encode-plus-char API property; if set to a value of true, all "+" characters in the query parameter values of the target-url of Invoke and Proxy policies are encoded to "%2F". In previous releases, + were always encoded to %2F. Now, the default behavior is to not do the encoding. See API properties.
You can enforce the JSON parser on the response rule for an Invoke or Proxy policy
From API Connect Version 5.0.8.3, there is a new x-ibm-gateway-api-enforce-response-limits API property; setting this property to a value of true allows the JSON parser to be enforced on the response rule. If the response body size is higher than the JSON parser limit set in the DataPower domain, a status code of 500 is returned. See API properties.
Potential for performance improvement to the map policy
From API Connect Version 5.0.8.3, there is a new x-ibm-gateway-optimize-schema-definition API property that can provide a performance improvement to the map policy when a very complex schema definition is referenced by a policy output definition. See API properties
New API event field
From API Connect Version 5.0.8.2, the endpoint_url event record field identifies the proxy or invoke target URL on which the request failed. See API event record fields for more information.
Identifying and resolving an analytics split-brain condition in a cluster
From API Connect Version 5.0.8.2, you receive an email notification when your system identifies multiple Elasticsearch nodes as the master node. This is also known as an analytics split-brain condition. See Analytics split-brain for more information about identifying and resolving this condition.
Deleting user accounts and Developer organizations in the Developer Portal
From API Connect Version 5.0.8.2, you can delete your user account and Developer organizations in the Developer Portal. You can also change the ownership of your Developer organizations. For more information, see Deleting your Developer account, Deleting a Developer organization, and Changing the ownership of a Developer organization.
Obtain simple health check data of Developer Portal sites by using a REST API call
From API Connect Version 5.0.8.1, you can call a simple health check API to determine whether a particular Developer Portal site is working. This API is very fast and puts no load on the system, so it is ideal for use with load balancers to help them determine where to route traffic. For more information, see Obtaining simple health check data of Developer Portal sites by using a REST API call.
View and select ciphers for TLS protocol versions used in TLS server profiles
From API Connect Version 5.0.8.2, you can view and edit the list of enabled ciphers for each version of the TLS protocol that is supported in a TLS profile. For more information, see Setting the ciphers for TLS Server profiles.
Secure individual APIs with TLS mutual authentication
From API Connect Version 5.0.8.1, you can secure individual APIs with TLS mutual authentication. An application that calls the API must supply a valid X509 certificate. For more information, see Composing a REST API definition.
Configure a Gateway service to use Server Name Indication (SNI)
From API Connect Version 5.0.8.1, you can use Server Name Indication (SNI) to specify which of two or more TLS profiles should be used depending on the host name. The SNI capability enables you to serve multiple endpoints through the same Gateway service without requiring them to use the same TLS certificate. For more information, see Configuring the initial Gateway service or Adding more Gateway services.
Specify multiple OAuth redirect URLs for your application in the Developer Portal
From API Connect Version 5.0.8.1, you can specify multiple URLs that authenticated OAuth flows for your application should be redirected to. For more information, see Registering an application.
Added support and a reference for Developer Portal REST APIs for analytics
Developer Portal REST APIs help you analyze your catalog APIs. For more information, see Analytics.
Added the Analytics section when creating an API
You can define and specify existing Parameters for your API that can be used to gather analytics data about the API. See Composing a REST API definition for more information.
Added the logs option to the system clean command
Specifying the logs option with the system clean command removes all of your log data from your server. For more information, see System commands.
Added the analytics option to the system clean command
Specifying the analytics option with the system clean command removes all of your analytics data from your server. For more information, see System commands.
Customize the number of replicas of your Elastic clusters
You can select automatic updating of the number of replicas, or specify a static number. See ../com.ibm.apic.cmc.doc/manage_organizations_idp.html#manage_organizations_idp for more information.
Encourage the use of two-factor authentication in the Developer Portal
You can encourage users of your Developer Portal to set up two-factor authentication (TFA) on their account by applying a TFA Rules module. For more information, see Encouraging users to set up two-factor authentication on their Developer Portal account.
Features added to the integrated billing and payment management
Administrator:
  • Create monthly prepaid billing subscription Plans that your API customers can subscribe to with a credit card. See Billing for the use of your Products for more information.
  • Leverage a Stripe account to manage the payments for your subscriptions.
  • Specify a number of free trial days in your subscription Plan for new subscribers. Payment automatically begins after the trial days expire.
Customer:
Invoke automatically replaced in the gateway
The last invoke in your policy might be replaced by a proxy. This is done automatically by the gateway to improve performance. For more information, see: API properties.
The Linux distribution for the Developer Portal OVA is now based on Ubuntu Version 16.04
Support for Debian Version 7 is coming to an end in May 2018, so the Linux distribution for the Developer Portal OVA is now based on Ubuntu Version 16.04. For information about how to migrate your current Debian OVAs to the Ubuntu OVAs, see Migrating your Developer Portal OVAs from Debian V7 to Ubuntu V16.04.
New API event fields
Added the following API event fields:
  • billing.trial_period_days
  • billing.amount
  • billing.currency
  • billing.model
  • billing.provider
  • client_id
  • immediate_client_ip
  • latency_info2.task
  • latency_info2.ended
See API event record fields and Obtaining analytics data by using REST API calls for more information.
New query parameters for the Redirect URL
New query parameters have been added to the information available for a third party. The new parameters are provider, providerid, and g-transid. For more information, see Authenticating and authorizing through a redirect URL.
OAuth scope can be modified by third-party responses
You can configure an external server to override the API scope value. For more information, see: Scope.
Preventing browser CORS alerts in the Test tool
The API Designer Test tool sends requests from the browser that can trigger CORS alerts. To prevent CORS alerts, the Enable Proxy check box is provided to send test messages from the server that hosts API Designer rather than from the browser. For more information, see Testing an API with the API Designer test tool.
Revoke single OAuth tokens
If you are using the DataPower Gateway, you can now revoke a single OAuth token for an application. For more information, see Creating an OAuth provider API.
Secure APIs with third party OAuth instead of Mobile First Foundation
Secure your API with a third-party OAuth provider instead of the IBM MobileFirst® Foundation authorization server. For more information, see Integrating third party OAuth provider.
Secure your APIs with OpenID Connect
You can secure your APIs with OpenID Connect(OIDC) by using a pre-supplied sample OAuth Provider API that you customize in accordance with your OIDC configuration. For more information, see Securing your APIs with OpenID Connect.
SOAP update action no longer overwrites the API
When you update a SOAP API from a WSDL definition, only those sections of the API that are affected by the new WSDL are replaced, the other sections are unchanged. In previous releases, the update action completely overwrote the configuration of the SOAP API definition, including all design properties and assembly configuration. For more information, see Updating a SOAP API.
Use Honeypot for spam protection in the Developer Portal
Honeypot protection provides security mechanisms to protect your Developer Portal site from form submission by spam bots. If spam bot activity is detected, form submission is blocked. For more information, see Using Honeypot for spam protection.
Using the Views module in the Developer Portal

Create new views in the Developer Portal, such as content lists of Products, APIs, and applications, by using the Views UI module. For more information, see Using the Views module in the Developer Portal.

You can also follow a tutorial about creating a custom sort order view for a list of APIs; see Tutorial: Configuring a custom sort order view for APIs in the Developer Portal.

View cluster information by using Elasticsearch REST API calls
You can use Elasticsearch API calls to view a health status of red, yellow, or green for your identified clusters. For more information, see Obtaining cluster health information by using REST API calls.

[V5.0.7 or later]Version 5.0.7

Added the stat show apiconfig command to check the health of your Management server
From API Connect Version 5.0.7.2, the stat show apiconfig command returns information about your Management server. You can use this command to determine if your database is in good health before an upgrade, or run it regularly to ensure that your Management server is running correctly. See Testing Management servers for more information.
Dynamically determine the health of a Developer Portal cluster
From API Connect Version 5.0.7.2, you can check the status of a Developer Portal cluster by calling a cluster health REST API. For more information, see Obtaining health check data of Developer Portal servers by using a REST API call.
Multilingual support of API and Product definitions
From API Connect Version 5.0.7.2, you can create multilingual API and Product documentation by using an x-ibm-languages extension directly in the OpenAPI (Swagger 2.0) definition. For more information, see Using x-ibm-languages to create multilingual API and Product documentation.
Integrated billing and payment management for your APIs
Starting with API Connect Version 5.0.7.2, API providers can use the monetization capability in API Connect to create pricing plans and set rate limits for their API products, collect payments from API consumers, and analyze the usage of their monetized and free API plans. Usage analytics can either be processed by using the integrated API Connect analytics tools, or by offloading them to an existing external system. Your consumers can subscribe themselves to plans, and have their payments made through a credit card processing provider. For more information, see the API Connect developerWorks blog To win in the API economy, you need a modern approach to API monetization.
XML Name Space attributes are in a different order from previous releases

Starting with API Connect Version 5.0.7.2 and beyond, users might notice that the order of XML Name Space (XMLNS) attributes in XML content in API requests and responses can differ from previous releases.

The XML specification https://www.w3.org/TR/xml/ does not suggest a preferred order for XMLNS attributes. Best practice is to not rely upon the sequence of XMLNS attributes if you write custom parsing code.

API Connect no longer allows external DTD/entity references while parsing XML.
From Version 5.0.7.1, IBM API Connect is secured to forbid external references while parsing XML. XML documents (such as custom forms, XML requests, or XML responses) being parsed by APIConnect Gateway will fail if there is a reference to an external URL. For more information, see the Tech note at "Forbidden external reference" error and controlling external DTD/entity references.
Analytics component has changed
The Analytics component is now built using the Kibana V5.1 open source analytics and visualization platform. As a result, there are some visual and operational changes to dashboards and visualizations. For a summary of the key changes, see The screen elements of a dashboard. Other changes are highlighted within the relevant procedures for the analytics tasks.

The event data that is generated in the API Connect on-premises cloud and displayed by the Analytics component can now be exported to third-party systems as a real-time data feed for centralized data consolidation, enhanced monitoring, and richer analytical data processing. The default ability to view and work with analytics data in the API Connect user interfaces is retained, but you can also now choose to disable access to analytics data within API Connect if preferred. For more information, see Configuring destination targets for API Connect analytics data.

Analytics email notifications triggered when data that is collected on the disk reaches predetermined levels
When the amount of Analytics data that is collected on the disk exceeds 70%, 80%, and 90% of the available disk space, an informational email is sent out at each level. See Adding a new data disk to a Management appliance for more information.
API Connect integrates with IBM Product Insights for viewing management and Developer Portal node resource usage.
You can view some usage resources for your API Connect management and Developer Portal nodes in the IBM Product Insights interface by registering your API Connect environment with IBM Product Insights. See Resource metrics collected by the IBM Cloud Product Insights service for more information.
API Designer and API Manager have a new look
The API Designer and API Manager user interfaces have been restyled based on the Carbon design system. This change affects only their "look and feel," not functionality.
Application lifecycle workflow
By using the application lifecycle capability, you can have separate Development and Production endpoints for the same API. Applications that are subscribed to use the API initially have Development status, and can call the API only through Development endpoints. When application testing is complete, the application developer can request to upgrade the application to Production status; when the request is approved, the application is upgraded and can call the API through Production endpoints. For more information, see Managing the application lifecycle.
Application metrics dashboard is now available for Node.js applications
When you run a Node.js application (such as a LoopBack project) locally using the Developer Toolkit, you can view application performance metrics using the built-in application metrics dashboard. For more information see, Viewing the application metrics dashboard.
Catalog supports multiple DataPower Gateway services
You can configure a Catalog to use two or more DataPower Gateway services. Then by modifying the Gateway service endpoints, and configuring your DNS appropriately, you can route API calls to the required Gateway service. For more information, see Using multiple DataPower Gateway services with a Catalog.
Collectives are deprecated in favor of Docker Swarm and Kubernetes managed containers
IBM API Connect collectives are deprecated in IBM API Connect Version 5.0.7 in favor of container runtimes. For more information and background, see Open, scalable, flexible runtime management of APIs through API Connect enabled containers. For information on setting up and migrating to containers, see Installing a containerized runtime environment.

Existing customers can continue to use their collectives with IBM API Connect Version 5.0.7, and if wanted can expand their collective deployments to new servers. API Connect collectives are supported for existing customers until the end of support of IBM API Connect Version 5.0 (see Software lifecycle page for IBM API Connect Version 5.0). Until then, users of API Connect collectives are encouraged to migrate to container runtimes to take advantage of their agility and scalability.

New customers should not install API Connect collectives because this feature is no longer supported for new users.

Command-line tools now work with management server running on ports other than default 443
If you change the TCP port number on which the API Management server listens, the apic command-line tool will now work properly if you specify the port with the command-line --server option.
Developer toolkit supports API testing with the DataPower Docker container
When you test API from the Developer toolkit, you can now set an option to use the DataPower Gateway Docker container for a full set of security and policy capabilities. The toolkit synchronizes with the Gateway on save; you can now test product and plan level concepts; DataPower Gateway error logging and Request/Response logging are also integrated into the API Designer logging console.
Developer toolkit supports API testing with the special apic-dev Catalog name.
When you test API from the Developer toolkit, you can now use the special apic-dev Catalog to substitute assembly properties at run time. This behavior is adapted from the API Manager component. See, Configuring API definitions for container run times, at Migrating LoopBack applications from collectives to containers for how to configure this feature.
Developer toolkit supports vendor extensions
API Designer now supports OpenAPI (Swagger 2.0) extensions (also referred to as "vendor extensions"). For more information, see Adding an OpenAPI (Swagger 2.0) extension to an API definition (API Designer UI). The command-line tool apic extensions command is also available for working with extensions. For more information, see Toolkit command summary and Extensions commands.
JSON Web Token (JWT) can now be used to secure your API
You can now secure your API with JSON Web Tokens in two ways. You can use the jwt-generate policy or you can use a token that was generated external to IBM API Connect.
LoopBack 3.0 is now supported by API Designer and command-line tools
When you create a new LoopBack project with the API Designer or apic loopback command, you now have the option of creating a LoopBack version 3.0 project. For more information on LoopBack 3.0, see loopback.io.
OAuth shared secret can be provided by the end user, or randomly generated
The default OAuth shared secret used by API Connect can be customized. For more information, see Adding a gateway server.
OAuth integration with third-party providers

IBM API Connect can be configured to use a third-party for authentication and or authorization in compliance with the OAuth 2.0 specification: https://tools.ietf.org/html/rfc7662. For more information, see Creating an OAuth security definition.

An additional header, x-Introspect-, is provided for passing additional information to a third party provider. For more information, see Integrating third party OAuth provider.

New OAuth query parameters
Six new OAuth query parameters have been introduced.
appid = application id
org = organization name
orgid = organization id
catalog = catalog name
catalogid = catalog id
transid = transaction id used in the Gateway
For more information, see:Authenticating and authorizing through a redirect URL
Maximum consent control
Use maximum consent to specify for how many seconds the combination of any number of access and refresh token remain valid. For more information, see: Creating an OAuth provider API.
SNI support for the management traffic between API Connect and DataPower Gateway
To inject Server Name Indication (SNI) in communications between IBM API Connect and a DataPower Gateway, you set the hostname (rather than IP address). For more information, see Adding a Gateway server.
Support for Node.js V6 added
IBM API Connect now supports Node.js V6.x.

[V5.0.6 or later]Version 5.0.6

Added the stat show apiconfig command to check the health of your Management server
From API Connect Version 5.0.6.6, the stat show apiconfig command returns information about your Management server. You can use this command to determine if your database is in good health before an upgrade, or run it regularly to ensure that your Management server is running correctly. See Testing Management servers for more information.
(Technical preview) Build an IBM API Connect environment in a Docker container

By installing IBM® API Connect in a Docker container, you can run a complete IBM API Connect on-premises environment on your local machine. A Docker container installation of IBM API Connect is for development use only, it is not supported in a production environment. For more information, see Installing and configuring IBM API Connect in a Docker container.

(Technical preview) Create applications in the Swift programming language
You can create applications in the Swift programming language by using Swift Server Generator. Swift Server Generator provides developer toolkit commands for creating Kitura Swift applications based on data models that you define and attach to a data source. A full set of REST APIs for working with the back-end data is generated automatically.
Note: Support has been removed from Version 5.0.8.7.
Categorize APIs and Products in IBM API Connect
You can define categories for APIs and Products in the API Designer or API Manager UI, and have the option to expose them in the Developer Portal.
You can also configure taxonomies for your APIs and Products in the Developer Portal.
For more information, see Organizing your APIs and Products into categories and Displaying APIs and Products in categories.
Creating and configuring Rules in the Developer Portal
You can configure Rules to perform specific actions when they are triggered by specific events in the Developer Portal. For more information, see Rules in the Developer Portal.
Including metadata in the OAuth transaction
You can include arbitrary information as metadata during the OAuth authentication handshake. When the Metadata URL is configured, IBM API Connect sends a request header to the URL and stores the response in the token or payload containing the token. For more information, see OAuth metadata.
Enabling OAuth debugging support
You can activate debugging for OAuth that produces a more detailed report than just an error message. For more information, see Troubleshooting OAuth.
Testing OAuth 2.0 with the Developer Portal test tool
The testing tool in the Developer Portal supports the testing of OAuth 2.0 interactions. For more information, see Troubleshooting OAuth.
Disabling Server Name Indication (SNI)
The TLS extension, SNI, is enabled by default. Servers that do not support SNI typically ignore the extension if it is included, but in some situations compatibility issues can prevent connection. You can disable SNI with a toggle in the TLS profile. For more information, see TLS profiles.
SSLClientProfile and SSLServerProfile replacing SSLProxyProfile
Forward SSLProxy (and Crypto) is replaced with SSLClient. These new profiles support ephemeral ciphers (DHE and ECDHE), perfect forward secrecy, and Server Name Indication (SNI) extension. Note that DHE ciphers in DataPower SSLServerProfile use 2048-bit DH parameters (as server) and accept 1024-bit DH parameters (as client).
(V5.0.6.2 and later releases) Conversion of non-ASCII characters in XML bodies
Non-ASCII characters (above U+007f) in XML bodies are no longer converted to numeric character references.
Policy properties introduced
(Version 5.0.6.2 and later releases) One new policy property has been introduced to maintain feature availability. Previously, invoke policies were URL-decoded by default. The new behavior is to not decode by default. For examples and a list of invoke policy properties, see API properties.
(Version 5.0.6.3 and later releases) Two new properties for the invoke and proxy policies have been introduced to control suppression of the X-IBM-Client-Id HTTP header and, in the case of the proxy policy, the client_id query parameter in the request URL. In previous releases, the client ID parameter was always suppressed. For more information about the invoke policy and proxy policy properties, see API properties.

[V5.0.5 or later]Version 5.0.5

Use the new syndication feature to partition your Catalogs
With the IBM API Connect syndication feature, you can partition your Catalogs into Spaces. Each Space is used by a different API provider development team and has its own set of management capabilities relating specifically to the APIs that the associated team publishes to that Space, enabling each team to manage their APIs independently. For more information, see Using syndication in IBM API Connect.

New developer toolkit CLI commands are provided to support the creation and management of Spaces, and there is a new space configuration variable. For more information, see Toolkit command summary.

Advanced XML options
You now have greater control over the namespace declarations in XML output of the map policy. For more information, see The map policy structure.
New Generate LTPA Token built-in policy
Lightweight Third Party Authentication (LTPA) is an IBM protocol that provides a cookie or binary security token based authentication mechanism in WebSphere® Application Server. Apply the Generate LTPA Token policy to your assembly so that your API can securely authenticate with applications or services that are hosted on WebSphere Application Server. Use the API Manager UI to import an LTPA key, and then apply a Generate LTPA Token policy to generate a Lightweight Third Party Authentication (LTPA) token.

For more information, see LTPA keys and Generate LTPA token policy.

Analytics enhancements
In the API Manager UI, the Analytics component includes the following updates for the syndication feature:
  • The Analytics permission is now Catalog-based rather than organization-based, and includes support for two separate actions: View (which provides read-only access) and Manage (which provides write access). The ability to access and work with analytics data at a Catalog or Space level will depend on the roles you are assigned and the type of Analytics permission defined for those roles.
  • An inheritance flow is defined for the dashboards and visualizations in a Catalog and its Spaces. This flow determines whether updates made to the dashboards and visualizations in a Catalog are reflected in a Space, and affects what you see when you attempt to edit, delete, or restore default dashboards or visualizations, or when you attempt to create, edit, or delete custom dashboards or visualizations.

    For more information, see Analytics and syndication.

Customizations to the default dashboards or visualizations can now be reversed by using the restore feature to reset your changes. For more information, see Restoring the default dashboards and Restoring the default visualizations.

[V5.0.5 only]While creating or editing a dashboard, the workflow has been improved to enable you to seamlessly create and add visualizations to the dashboard during the process. For more information, see Creating custom dashboards and Editing dashboards.

In the Cloud Manager, analytics data can now be accessed for the individual servers in the Management and Gateway services. For more information, see Monitoring the health of the individual servers.

OAuth support for test tools
The test tools in the Developer Portal, and the API explorer and assembly console that are found in the API Manager API Designer UIs now support OAuth. The test tools can act as full OAuth clients, which enables the complete testing of APIs that are secured with all of the OAuth2 flows.
Adding custom pages to APIs and Products
You can add any custom pages that you have created to any APIs and Products that exist in the Developer Portal. By adding custom pages to APIs and Products, you can include additional information to APIs and Products that might improve their use and implementation. For more information, see Add custom pages to APIs and Products.
Open API formData support for the Developer Portal test tool
The test tool in the Developer Portal now supports the use of formData in Open API documents.
Reuse code fragments in OpenAPI (Swagger 2.0) files
You can use the $ref field in your OpenAPI (Swagger 2.0) API definition files to reference a fragment of OpenAPI (Swagger 2.0) code that is defined in a separate file. When IBM API Connect processes the source API definition file, the $ref field is replaced with the contents of the target file. For more information, see Using $ref to reuse code fragments in your OpenAPI (Swagger 2.0) files.
New toolkit commands to view and list subscriptions
The apic subscriptions and apic subscriptions:get commands list subscriptions in a product, application, or a Catalog and display information on a subscription, respectively. For more information, see Toolkit command summary.
New toolkit command to list members of an organization
The apic members command lists members of an organization. For more information, see Toolkit command summary.
Configure plan, rate-limit, and TLS profiles in Micro Gateway Datastore

Developers are now enabled to configure plan, rate-limit, and TLS profiles in the Micro Gateway Datastore for a better development experience.

Configure writable LDAP in the Developer Portal
You can configure writable OpenLDAP in the Developer Portal if you already have an existing LDAP and want to include additional users.
For more information, see Configuring writable LDAP in the Developer Portal.
Obtaining metrics data for your LoopBack applications

You can monitor your LoopBack® applications by obtaining metrics data. You can send the metrics data to a variety of logging destinations. For more information, see Obtaining metrics data for your LoopBack applications.

New tutorial flow diagrams
Each developer toolkit tutorial displays a tutorial flow diagram to make it easier for you to follow the tutorials in the correct sequence.
Minature tutorial flow diagram
When you are on a tutorial page, you can click a tutorial in the diagram to open that tutorial directly. You can access the developer toolkit tutorials at Developer toolkit tutorials.

[V5.0.4 or later]Version 5.0.4

Gateway support for custom branding
When you implement custom branding, you no longer need to add a component to map the URL. URL mapping is no longer required because the gateway detects the Catalog based on the incoming host name. For more information, see Creating and configuring Catalogs.
Advanced XML options
You now have greater control over the XML output of the map policy. You can control empty elements, and inherited namespaces. For more information, see The map policy structure.
Secure your APIs with IBM MobileFirst Foundation
You can now secure your IBM API Connect APIs by using the IBM MobileFirst Foundation authorization server.
Ability to view and export API event data from Analytics
From the API Manager user interface, you can view the individual API event records that are generated for the aggregated data sets in your visualizations, and you can collectively export all the API event records that relate to all visualizations in a dashboard. The event data that you export is saved to a comma-separated values (CSV) file. For more information, see Viewing and exporting analytics and event data.
Toolkit CLI accessibility mode
Developer toolkit accessibility mode makes the product easier to use for those with limited eyesight. To enable accessibility mode, set the accessibility-mode configuration variable to enabled. In this release, when you enter the apic edit command in accessibility mode, the tool prompts whether you want to open the API Designer in your web browser. For more information about setting configuration variables, see Using configuration variables.
New CLI commands
Two new apic commands were added: apic orgs:get and apic devapps.
For more information, see Toolkit command summary.
Automatic subscription support with the Micro Gateway
You can now enable Automatic subscription for a Catalog that uses the Micro Gateway, in addition to the DataPower Gateway.

Enabling automatic subscription makes testing of your APIs in the API Manager user interface easier because a test application is used, with a pre-supplied client ID and client secret, which is automatically subscribed to all the Plans in the Catalog. As a result, you don't have to specify a plan or application when testing. For more information, see Creating and configuring Catalogs.

Ability to create an API and Product definition from a custom template using the API Designer
In the API Designer, you can now create a new API or Product definition from a custom Handlebars template file. For more information, see Composing a REST API definition and Creating a Product in the API Designer.
Link checking in the Developer Portal
You can now periodically check for any broken links in your Developer Portal. For more information, see Checking links in the Developer Portal.
Default language for code snippets in the Developer Portal
Any user of the Developer Portal can select the default programming language that their code snippets are displayed in. For more information, see Selecting the default code snippet language.

[V5.0.3 or later]Version 5.0.3

The built-in validate policy is now available on the Micro Gateway
You can now use the validate policy with the Micro Gateway to validate the payload in an assembly flow against a JSON schema. For more information, see validate.
Note: You can continue to use the validate policy with the DataPower Gateway to validate the payload in an assembly flow against a JSON or an XML schema.
OAuth introspection endpoint
You can now add an introspection operation to an OAuth provider API. This new endpoint allows applications to present an OAuth access token and receive information about the access token in the response. For more information, see Creating an OAuth provider API.
Enhanced graphical user interface support for arrays and inline schema in the map policy
A graphical method for creating new inline schemas is now available for the map policy, enabling you to easily create schemas in the map policy that are not exposed to the users of your API. Additionally, support for iterating over different levels of arrays is provided when configuring a particular mapping without editing the OpenAPI (Swagger 2.0).
More detail in the debug view of the API Manager test tool
DataPower Gateway onlyAdditional debug information, such as the input and output of the policy, is available for the invoke, map, and proxy policies.
New automatic subscription mode for a Catalog
DataPower Gateway onlyIn the API Manager user interface, you can now enable Automatic subscription for a Catalog. Enabling automatic subscription makes testing of your APIs in the API Manager user interface easier because a test application is used, with a pre-supplied client ID and client secret, which is automatically subscribed to all the Plans in the Catalog, so you don't have to specify a plan or application when testing. For more information, see Creating and configuring Catalogs.
Admin guide in the Developer Portal
An admin guide is available in the Developer Portal to administrator accounts, only. The admin guide include information that ranges from basic configuration of the Developer Portal, to managing security and users. The information in the admin guide contains information from the Knowledge Centre.
Code snippet enhancements in the Developer Portal
You can choose which languages can be used to display code snippets in the Developer Portal. C and C# are also added to the collection of languages that you can enable to become available. For more information on configuring the languages that are available for code snippets, see Enabling code languages for code snippets. For more information on code snippets, see Browsing available APIs.
Creating and applying Rules in the Developer Portal
You can create rules in the Developer Portal which automatically trigger actions in response to situations or other actions. By creating rules, you can automate and anticipate responses to situations, which can help provide a more personalized and efficient user experience. For more information, see Applying rules in the Developer Portal.
API Designer can now create new LoopBack and OpenAPI projects
You can create new LoopBack and OpenAPI projects directly within the API Designer. For more information, see Creating new projects in the API Designer
The apic login command has a new --sso option
The --sso option enables you to login to IBM API Connect cloud using federated corporate ID.
Terminology changes
IBM API Connect Version 5.0.3 introduces the following terminology change:
Previous term New term
Sandbox Catalog Development Catalog
Note: The title of the pre-supplied default development Catalog remains as Sandbox.

[V5.0.2 or later]Version 5.0.2

Using the Portal Delegated User Registry in the Developer Portal
By enabling the Portal Delegated User Registry in the API Manager UI, you can improve the flexibility of user registry and account management using the additional configuration options that are available in the Developer Portal. For more information, see Portal Delegated User Registry.
You can use the log in credentials that are used with external authentication providers (such as Facebook, Google, or Twitter), to access the Developer Portal. Using external authentication provider credentials reduces the number of authentication credentials that a user has. For more information, see Using external authentication provider credentials to access the Developer Portal.
Your Developer Portal site can manage users and user registries. Therefore, you can configure your LDAP user registry in the Developer Portal. For more information, see Configure your LDAP user registry in the Developer Portal.
You can modify the templates that are used for the emails that are sent by the Developer Portal, by altering the content and tokens that the emails use from within the Developer Portal. For more information, see Modifying the Developer Portal email templates.
Enhancements to the OpenAPI (Swagger 2.0) extension capability
The capability to add OpenAPI (Swagger 2.0) extensions to your APIs has the following enhancements:
  • You can now add extensions to your local API definitions by using the API Designer user interface, in addition to the API Manager user interface.
  • You can replace an extension with an updated version.
  • The schema definition file for the extension is in YAML format rather than JSON format.

For more information, see Adding an OpenAPI (Swagger 2.0) extension to an API definition (API Designer UI) and Adding an OpenAPI (Swagger 2.0) extension to an API definition (API Manager UI).

Uploading a WSDL file is now supported in the API Designer
You can now create a SOAP API in the API Designer user interface by uploading a WSDL file. You can upload the file either from your local file system or from a URL.

For more information, see Adding a SOAP API definition.

Defining the main site in your API Connect cloud
By defining a main site in your API Connect cloud, you can ensure that your specified server configurations are preserved if a network link between sites is interrupted. For more information, see Define the main site in your API Connect cloud.
Apply multiple burst limits and multiple rate limits to your Plans and operations

You can now set multiple rate limits per Plan and per operation, at second, minute, hour, day, and week time intervals.

DataPower Gateway onlyYou can also apply burst limits to your Plans, to prevent usage spikes that might damage infrastructure. Multiple burst limits can be set per Plan, at second and minute time intervals.

For more information, see Working with Products in the API Designer.

New built-in WS-Security policy: validate-usernametoken
Apply the validate-usernametoken policy to your APIs to validate a Web Services Security (WS-Security) UsernameToken in a SOAP payload, before allowing access to a protected resource. For more information, see validate-usernametoken.
Using templates to create APIs and Products
Using the CLI, you can create API and Product definitions from templates. Template files are Handlebars templates containing variables of the form {{variable-name}} that are substituted with values when you create the API or Product definition. For more information on using templates, see:
API Designer can discover models from relational databases
You can use API Designer to create models corresponding to existing database tables. This process is called discovery and is supported by data source connectors for: MySQL, Oracle, PostgreSQL, and SQL Server. For more information, see Discovering models from relational databases.
API Designer can create and update a database schema based on LoopBack models
You can use API Designer to create and update a database schema based on your models, for MongoDB, MySQL, Oracle, PostgreSQL, and SQL Server connectors. This enables you to develop your models first, and create (and update) your database schema to match them. For more information, see Creating database schema from models.
You can add an existing LoopBack or OpenAPI project to the API Designer.
Once you add a project, you can then edit it with API Designer and you can switch between multiple projects. For more information, see Adding an existing project to API Designer.

[V5.0.1 or later]Version 5.0.1

Managing disks on Management appliances

You can now protect your data by encrypting the hard drives on your Management servers. For more information, see Disk encryption.

When you upgrade a Management appliance to IBM API Connect Version 5.0, or install IBM API Connect Version 5.0 onto a new appliance, the amount of swap space and code disk size that is required is greater than in previous versions. For more information on the swap space and code disk requirements, see Swap space allocation and Increasing code disk size for appliances.

New JSON Web Token (JWT) built-in policies

JWT is a compact, URL-safe way of representing claims that are transferred between two parties. IBM API Connect now includes the following two built-in security policies that you can apply to your APIs:

  • jwt-generate

    Use the jwt-generate policy to generate claims and configure whether they are to be used as the payload of a JSON Web Signature (JWS) JSON structure, or as the plain text of a JSON Web Encryption (JWE) JSON structure. For more information, see jwt-generate.

  • jwt-validate

    Use the jwt-validate policy to enable the validation of a JSON Web Token (JWT) in a request before allowing access to the APIs. For more information, see jwt-validate.

Workbench moderation in the Developer Portal

You can use a dashboard to manage the review and approval process for content types in the Developer Portal. You can specify which roles can access the workbench dashboard by assigning them the appropriate permissions. For more information, see Configuring workbench moderation.

New OAuth token management system through DataPower

Manage the revocation of an OAuth 2.0 access token by using DataPower. The list of revoked access tokens is shared across your gateway cluster and access by using REST APIs, configured in your OAuth provider API.

[Available in beta]Using external authentication provider credentials to access the Developer Portal

You can use the log in credentials that are used with external authentication providers, to access the Developer Portal. Using external authentication providers credentials reduces the number of authentication credentials that a user has. For more information, see Using external authentication provider credentials to access the Developer Portal.

Web service invocation within the assembly of a REST API

You can add an existing web service to your REST API definition and then use it in your assembly, where the WSDL file of your web service is used to generate map policies to manage the invocation of the web service.

[V5.0.0 or later]Version 5.0.0

Offline developer experience with the developer toolkit

The developer toolkit provides all users with an offline developer experience. The offline developer experience enables the user to create their APIs with the API Designer visual editor, run tests locally, manage APIs and any security policies, ready for publishing to an appliance or to IBM Cloud in the future. The APIs can also be tested by running them through the Micro Gateway in an end-to-end flow. A command line environment is also provided. You create local definition files for your APIs and then use either the editor or the toolkit commands to interact with API Manager.

For more information, see Developing your APIs and applications.
Visual editor for composing APIs

The Assemble view in the new API Manager user interface provides a visual tool for composing API assembly flows. You drag and drop components from a palette into your API assembly diagram. Additionally, a Code view provides an OpenAPI (Swagger 2.0) editor. Any changes that you make to your assembly diagram in the Assemble view are reflected in the Code view; similarly, if you change the OpenAPI (Swagger 2.0) code directly, the assembly diagram is updated accordingly. For more information, see The assemble view and The source view.

Important: Due to a change in the OpenAPI (Swagger 2.0) specification, API definitions created before the first fixpack will not pass validation upon staging of their containing Product. For information on editing your API to rectify the validation error, see Composing a REST API definition.
Node based Micro gateway

Included in the offline developer experience is the Micro Gateway. The Micro Gateway is a node.js based gateway that builds on StrongLoop® technology, and is packaged and available through npmjs.org as one of the components of the apiconnect package. The Micro Gateway receives requests, processes them as defined in the assembly, and invokes the back-end API all on a laptop. The policies available in the Micro Gateway are a subset of those available in the DataPower Edge Gateway.

Create and run

In addition to managing and securing APIs, you can now create and run APIs in IBM API Connect by using the LoopBack capabilities that are included in the single integrated offering. For more information, see Working with LoopBack projects.

Redesigned API Manager user interface

The API Manager user interface has been redesigned to enhance the API management experience. For full details about how to use the API Manager user interface, see Managing your APIs.

Improved visualization for analytics

You can create custom analytics dashboards for your Catalogs through API Manager, which consist of default or user created visualizations such as tables, graphs, and maps. The analytics performance has also improved. For more information, see API Analytics.

APIs are published in a Product

APIs are now published inside a Product. Products provide a method by which you can group APIs into a package that is intended for a particular use. Within a Product, APIs are contained in Plans that can be used to differentiate between offerings, and enforce rate limits. For more information, see Working with Products in the API Designer and Working with Products in the API Manager.

Removal of the Basic Developer Portal

The Basic Developer Portal has been removed from IBM API Connect. The Advanced Developer Portal is renamed to the Developer Portal, and is available to everyone.

The Developer Portal provides additional features including forums, enabling application developers to find and use APIs, blogs, comments, and ratings, together with an administrative interface for customizing the Developer Portal.

New features for the Developer Portal (formerly known as the Advanced Developer Portal)
  • Improved responsive design layout for the Developer Portal.
  • New social block in the Developer Portal for forum posts and tweets. For more information, see Integrating Twitter data into the social block.
  • New features for the API/Product block
  • You can uninstall themes or module files from the server by using the new Comprehensive Uninstaller.
  • You can increase the specificity of a Developer Portal site URL by using sub paths. For more information, see Sub paths for the Developer Portal sites.

For more information, see Developer Portal.

Custom OAuth forms

You can now implement custom forms for the sign-in and authorization stages of the OAuth security flow. For more information, see Creating a custom sign-in form and Creating a custom authorization form.

New built-in policies
The following additional built-in policies are provided, which you can optionally apply to your APIs:
invoke
Call an existing service from within an operation.
if
Execute a section of the assembly when a condition is fulfilled.
throw
Configure errors returned by your API.
map
Transform variables with enhanced capabilities compared to previous versions of API Management.
xml-to-json and json-to-xml
Convert between xml and JSON schemas by using the badgerfish protocol.
activity-log
Log fields during an API call.
xslt
Perform an xslt transformation.
gatewayscript and javascript
Include a GatewayScript or JavaScript program in your assembly.
redact
Remove unwanted or confidential fields during an API call.
validate
Validate the payload in an assembly flow against a schema
set-variable
Set a runtime variable to a string value, or add or clear a runtime variable
operation-switch:
Execute sections of the assembly depending the operation that is called.

For further details, see Built-in policies.

REST authentication for product APIs under IBM ID

If you are using IBM API Connect for IBM Cloud (the SaaS offering), you can now provide your IBM ID credentials when you make REST requests to the API Manager or Developer Portal. This is useful when you attempt to automate the creation and management of applications. For more information, see Developer Portal REST APIs and Obtaining analytics data by using REST API calls

Upgrading the Management server

Effective with this release, it is important to take a virtual machine snapshot prior to upgrading the Management servers (and not only of the API Management configuration backups). Otherwise, you might be unable to restore the API Management configuration backup directly to the Management servers and would need to set up a new virtual machine.