Known limitations

Analytics

Instana AutoTrace and Dynatrace injection are not supported in certain subsystems

Instana AutoTrace is not supported in the Management, Analytics, Developer Portal, and Gateway subsystems. Using Instana AutoTrace in these subsystems can cause corruption; additionally, Dynatrace injection is not supported in the Developer Portal subsystem and can cause corruption. For more information, see Instana AutoTrace.

Note:

• OpenTelemetry based tracing from the DataPower® API Gateway is supported and is the recommended method. For more information, see Enabling OpenTelemetry configuration.
• This issue originates from the Instana integration and is not related to API Connect.

Analytics command restrictions

The following --mode analytics commands work only when the flag --return_format is set to either json or yaml:

• clustermgmt:catAllocation
• clustermgmt:catIndices
• clustermgmt:catNodes
• clustermgmt:catRecovery
• clustermgmt:catShards
• clustermgmt:catAliases

The following commands don't currently work on the Toolkit CLI, as they return only text/plain:

• clustermgmt:getNodesHotThreads
• clustermgmt:getNodesHotThreadsById

Consumer rate limit notifications are not available in Version 10

The ability to configure notifications for applications so that API consumers are alerted when the usage of an API is nearing its rate limit is not available.

API governance

Validating from within a ruleset shows all rules

In the governance service, if you click Validate from within a ruleset, the list of rules shown includes rules that are not part of the selected ruleset. To work around this, manually select the rules that you want to use for the validation.

API Manager

Incomplete API selection when creating draft products with multiple APIs

When creating a draft product, not all selected APIs are saved if multiple APIs are chosen simultaneously.

An OAuth provider fails if the resources that it references aren't enabled in the Catalog

If you enable an OAuth provider in a Catalog then any resources that it references, such as API user registries or TLS client profiles, must be enabled in the same Catalog; if not, then although the OAuth provider might publish successfully it will fail at run time. For information on enabling resources in a Catalog, see Creating and configuring Catalogs.

Incorrect UI behavior if API changes are not saved before creating a new API version

If you make changes to an API definition and then attempt to create a new API version without first saving your changes, you are not prompted to save your changes until after you have completed the new version creation operation. If you click OK in the prompt, your new version is created but your original changes are lost; to create your new version and retain your original changes, you should click Cancel in the prompt, then click Save to save your original changes.

Simultaneous editing of the same API by multiple users might result in changes being overwritten

If one user saves changes to an OpenAPI 3.0 API, another user who has the same API open in the API editor might have their changes overwritten.

An existing user cannot be added to a Space

If you attempt to add an existing user to a Space, the operation cannot be completed because the Create button is not enabled. Instead, use the invitation mechanism. For details, see Managing Space membership.

Note: The invited user must use the Sign in option on the activation form, rather than completing the registration details and using Sign up.

A published API whose assembly contains a catch block with an invalid policy will now correctly fail to republish

Previously, policies in an assembly catch block were not validated, so if an incorrect policy configuration was coded in the OpenAPI source for an API, within an assembly catch block, the API would still publish successfully. Now, policies in an assembly catch block are validated, so such an API will fail to republish and will first need to be corrected.

Cloud Manager

Cloud Pak for Integration

Gateway

WebSocket support

API Connect provides basic WebSocket functionality through the websocket-upgrade policy. However, there are important limitations to consider when designing APIs that use WebSocket communication.

1. General limitations
   • The maximum reliable message payload is less than 1 KB.
   • Sending several messages in rapid succession may exceed cumulative limits. For example, three consecutive 500-byte messages may fail.
   • Messages up to 100 bytes can be reliably transmitted if sent with at least a 10 millisecond delay between them.
   • Send data at intervals greater than 10 milliseconds to prevent dropped connections or gateway issues.
   • WebSocket compression and streaming modes are not supported.
2. Error handling limitations
   • When a server closes a connection using status code 1000, 1006, or 1008, the client receives code 1006, regardless of the actual cause.
   • If the server crashes, the client does not receive a close event or error message from the DataPower Gateway.
   • Errors can be caught:
     • In the main assembly before the websocket-upgrade policy is executed.
     • In sub assemblies during message processing after the upgrade that originate from a subassembly action.
   • Errors during WebSocket connections or after disconnection cannot be detected once the upgrade is complete.
3. Opcode and data type support
   • Only text frames are supported.
   • Binary frames are not supported.
4. Policy restrictions after upgrade
   • After the WebSocket upgrade, the following actions and properties are not supported in the sub assemblies:
     • client security
     • generate JWT
     • user security
     • validate JWT
     • client identification
     • activity log
     • HTML page
     • WebSocket upgrade
     • Parse:
       • use content type
       • warn on empty input
   • No actions are allowed in the main assembly after the upgrade.
   • Only sub assemblies that use supported properties can process messages after the upgrade.

PK12 Key/Cert pairs created with legacy algorithms are not supported for use with the apic-gw-service

As a result of increased security requirements in IBM API Connect 10.0.8.0, if you configured your non-container gateways to use a PK12 cert/key pair that was generated with legacy algorithms, the Gateway service will fail to start.

Logs will show the following message:

[0x88e00011][apic-gw-service][error] apic-gw-service(default): API Connect Gateway Service 
caught unhandled rejection: Error: All sentinels are unreachable. Retrying from scratch after 10ms. 
Last error: unsupported

To resolve this problem, you must create a new key/cert pair and update your apic-gw-service object with this configuration. This can be done directly through the DataPower crypto tools, or through a third-party tool such as OpenSSLv3. note that OpenSSLv1 cannot be used because defaults to the legacy algorithms.

Redact on invalid XPath fails after converting to DataPower API Gateway

Redact on invalid XPath fails after converting to DataPower API Gateway. Application
Management Unit (AMU) version 10.0.8.0-R0 support the conversion of the Redact
policy, but only to Redact version 1.5.0, not 2.0.0.

Redact conditions within switch, operation-switch, or if policies might not execute after converting to DataPower API Gateway

If an API Connect v5-compatible redact policy is found within a switch, operation-switch, or if policy, the migration utility does not move the redact policy to the beginning or end of the assembly. The difference in the response between API Connect v5 and DataPower API Gateway may prevent data from being redacted in the DataPower API Gateway.

For example, if an assembly includes a switch policy containing four redact conditions followed by an invoke policy, each redact condition redacts the response data. After porting to the API Gateway, the redact conditions remain inside the switch policy and target the message.body property for redaction. These redactions fail to execute because the message.body property has not yet been retrieved by the invoke policy. To correct this problem, you must move the invoke policy before the switch policy in the assembly.

Auto-publishing and testing limitations for v5c Gateway APIs in API Designer and API Manager

In API Designer and API Manager, v5c gateways do not support auto-publishing or API testing using the Test tab. In v5c gateways, the Test tab is unavailable and does not appear in the API editor.

Parse policy limitation

• The literal property in the parse policy does not support variables or context parameters. It must be a fixed string.

Developer Portal

The 'strict' SameSite cookie causes incorrect invitations to consumer organizations

Using the 'strict' SameSite cookie might cause invitation links from emails to send users to a registration page where they are asked to create a new consumer organization instead of joining the organization they were invited to.

The workaround is to using the 'Lax' SameSite Cookie attribute.

IP-based Portal security features not supported in V10 Reserved

The V10 Reserved network topology does not preserve true client IP addresses, so IP-based security features in the Developer Portal do not work as expected.

Platform

Warning message after upgrading from version 10.0.5.x to version 10.0.8.x

After upgrading from API Connect v10.0.5.x to v10.0.8.x, users encounter the following warning message in the analytics component:

Warning: The transform of API event data into long term summary data has encountered problems. Contact your system administrator to investigate further. Long term summary data in reports may not be complete.

This warning is displayed because API event data processed by v10.0.5.x cannot be transformed into long-term summary data that uses v10.0.8.x.

The warning does not affect analytics functions or the accuracy of newly processed data in version 10.0.8.x. To resolve the warning automatically, ensure that the data retention policy is properly configured. As older data is purged, the warning clears. To update the retention settings, see Retention and rollover.

Toolkit

API Designer with Local Test Environment (LTE) fails to log in using https://localhost with the error message "Incorrect username, password, or credentials"

If you use the API Designer with the Local Test Environment and attempt to log in using the localhost, the login fails. You can work around the issue by configuring API Designer credentials to with the local host. Complete the following steps:

1. Download and extract API Designer, then install the credentials file as explained in .

2. Edit the designer_credentials.json file and configure the following settings:
   • "endpoint": "https://localhost"

   • "manager_endpoint": "https://localhost/manager"

   • "client_id": Client Id

     The client ID displays on the console when you start the LTE platform-apic-lte. For more information, see Testing an API with the Local Test Environment.

   • "client_secret": Client Secret

     The client secret displays on the console when you start the LTE platform-apic-lte. For more information, see Testing an API with the Local Test Environment.

3. Start API Designer and log in with the LTE using https://localhost as the Host URL (the management endpoint).

API Designer might hang while activating a large imported API

When you import a large API using API Designer and attempt to activate the API in the import wizard, the process might hang. If you encounter this issue, you can work around the problem by completing the following steps:

1. On your local file system, locate the autoproduct file called API-NAME-auto-product_API-VERSION.yaml.
2. Delete the file.
3. In API Designer, edit the newly imported API and activate it by clicking the Online toggle.

In general, it is best practice to activate an API using the Online toggle or by publishing the API with the Publish option.

API Designer on Windows: APIs that use WSDL might encounter errors, or fail to activate, publish, or update.

If you activate, publish, or update a REST or SOAP API that uses a WSDL file, the operation might fail and never complete. Work around the issue by using the autopublish API feature in the API editor.

Permission restrictions in the API Designer UI

The API Designer UI currently has the following permission restrictions:

• Developers that have been given only View permissions cannot see the Test tab in the API editor. For developers to be able to see the Test tab, they must be given a different permission level. For information about the default permission levels available, see API Connect user roles.
• Users with API-Drafts permissions, but who don't have any Sandbox Catalog permissions, cannot see the Test preferences in the Sandbox Catalog. For these users to be able to see the Test preferences, they must be given the Developer or Administrator role on the Sandbox Catalog.

Deleted security requirements might remain in the API source

Security requirements that are deleted from APIs in the API Designer and API Manager UIs, might still remain in the source. To work around this issue, click the Source icon in the API editor, and manually remove the security requirements.

Cannot add comments to APIs by using the Source view in the API Designer and API Manager UIs

Comments cannot be added to APIs in the API Designer and API Manager UIs by clicking the Source icon , and using the hashtag symbol.

Changing Product visibility from Custom to Public doesn't automatically remove the Consumer organizations and groups

In the API Designer and API Manager UIs, changing Product visibility from Custom to Public doesn't automatically remove the consumer organizations and groups, so the Product publish will fail. To work around this issue, manually remove all of the consumer organizations and groups.

The "Select compatible gateway services" option in Test Preferences causes a "404 POST undefined" error while testing the API

In the Test Preferences > Target gateway services setting, selecting Select compatible gateway services and choosing a specific gateway results in a "404 POST undefined" error when you test the API in the API Explorer or the Test tab.

Workaround: To avoid this problem, select the Use all compatible gateway services target gateway option instead.

Limitations to the OpenAPI 3.0 support

IBM API Connect supports the OpenAPI 3.0 specification, with some limitations. For information about what is supported, see OpenAPI 3.0 support.

A GraphQL API that contains a graphql-input-type-cost rate limit fails to publish

A GraphQL API created in releases earlier than IBM API Connect Version 10.0.3.0 might contain a graphql-input-type-cost rate limit, which is no longer supported. If you attempt to use the automatic activation mechanism to publish the API, or manually add the API to a Product and attempt to publish that Product, the publish operation will fail. You can resolve this problem in either of the following ways:

• Remove the rate limit definition from the OpenAPI source for the API. For example, if the source is in YAML format, remove the following lines:

  - name: graphql-input-type-cost
    operation: consume

• Edit the source for the Product and define a graphql-input-type-cost rate limit in all of the Plans that include the API.
  Note: You can edit only a manually created Product, not a Product that is generated by the automatic activation mechanism.

Cannot publish an API that has duplicate security definition entries

The API Designer and API Manager user interfaces allow you to add duplicate security definitions to an API. However, attempts to publish the API will fail with OpenAPI validation errors. Ensure that the security definitions in an API are unique.

No option to bulk delete APIs or Products

In the API Designer and API Manager user interfaces, there is currently no option to delete multiple APIs or Products in a single operation; in the user interfaces, APIs and Products must be deleted individually. However, you can bulk delete APIs and Products by using the REST API or CLI interfaces.

Field validation for the Client security policy is incorrect

When configuring a Client Security policy in an API assembly in the API Designer or API Manager user interfaces, there is the following incorrect validation behavior:

• The ID Name field is required, but the API definition can be saved without entering a value in the field.
• The Secret Name field is required only when the Secret Required option is selected, but the user interface indicates that the Secret Name field is required regardless. Furthermore, when the field is required, the API definition can be save without entering a value.
• If the Authenticate Client Method is set to Third party, the User Registry Name field is required, but the API definition can be saved without entering a value in this field.

An OpenAPI definition that contains regular expression syntax fails validation

IBM API Connect supports the GO regular expression syntax. When you import an OpenAPI definition into the API Designer or API Manager user interfaces, or validate one with the apic validate, the validation will fail if the OpenAPI source contains unsupported regular expression syntax, with errors that include Does not match format 'regex'; for example:

- Must validate at least one schema (anyOf) (context: (root).paths./example/types.post.parameters.0.schema.properties.items, line: 0, col: 0)
- Must validate one and only one schema (oneOf) (context: (root).paths./example/types.post.parameters.0, line: 46164, col: 21)
- paths./example/types.post.parameters.0.schema.properties.items.properties.pattern Does not match format 'regex' (context: (root).paths./example/types.post.parameters.0.schema.properties.items.properties.pattern, line: 0, col: 0)

Validate policy limitations when GraphQL response contains a GraphQL server error

When a GraphQL response contains a GraphQL server error and no data, the assembly Validate policy generates an error on the missing data and overwrites the payload. When the response contains partial data and an error, the assembly Validate action validates the data and overwrites the payload. To work around this limitation, use the condition $not($exists(message.body.errors)) in an assembly switch condition to skip the assembly Validate policy when the response contains errors.

An API developed for IBM API Connect Version 2018.4.1 that uses an apim.getvariable('message.body') function call fails in IBM API Connect Version 10

With the DataPower API Gateway in IBM API Connect Version 2018.4.1, the type of object returned, for XML payloads, by an apim.getvariable('context_name.body') function call in a GatewayScript policy in an API assembly depends on how the variable is stored in the gateway context, as follows:

• If the variable is stored as a Buffer (because the variable data was written as an XML string), an XML Nodelist is returned provided that contextname.headers.content-type is an XML type.
• If the variable is stored as a parsed XML Document (because the variable data was written as parsed XML, either as an XML document or an XML Nodelist), an XML document is returned.

With the DataPower API Gateway in IBM API Connect Version 10 however, the same function call always returns an XML Nodelist provided that contextname.headers.content-type is an XML type. Therefore, such an API developed for Version 2018.4.1 will fail in Version 10 if it is configured to expect an XML document, and will need to be reconfigured appropriately.

The problem does not occur with such an API migrated from IBM API Connect Version 5 because, with that release, apim.getvariable('context_name.body') also returns an XML Nodelist for XML payloads, nor does it occur if you are using the DataPower Gateway (v5 compatible).

context_name could be message, request, or the name of the output from an invoke policy.

For a secured GraphQL API, GraphQL subscriptions cannot be tested by using the Test tab in the user interfaces

For a GraphQL API that is secured by client ID, GraphQL subscriptions cannot be tested by using the Test tab in the API Designer or API Manager user interfaces. The API can still be published and used in production.

You can test GraphQL subscriptions in either of the following alternative ways:

• Remove client ID security from the API, for testing purposes, then use the Test tab.
• Use an external test tool.

User Interface

Audit event and related engagement sections are not functional in version 10.0.8.3

In version 10.0.8.3, the audit event and related engagement sections are currently non-functional. These sections might not display or log events as expected. Attempts to access them can result in HTTP 500 (Internal Server Error) or HTTP 403 (Forbidden) responses.

This issue is planned to be resolved in version 10.0.8.4.

Stale cache can result in unexpected behavior in the API Manager UI

Having a stale cache in your browser can result in unexpected behavior in the API Manager UI, such as fetch errors, incorrect data being displayed, and blank pages. To work around this issue, complete the following actions:

• Reload the browser window.
• If there is still an issue, clear the browser cache and then log back in to the UI.
• Try using a private browser window.
• If possible, try a different browser type.

If issues persist, contact IBM Support.

Limitations to the updated schema editor for API definitions

The Definitions section of the API editor for the API Manager and API Designer UIs was updated in API Connect. However, the OneOf, AllOf, and Enum schema structures aren't handled properly by the UI. You can work around this issue by editing the source YAML of your API document.

Options menus in the Catalog might be hidden

In a Catalog, in any of the different tabs such as Consumers, or Subscriptions, when clicking on the options icon the menu items might be hidden. To work around the issue, reload the page and the menu items will appear.

Override plan rate limits are not displayed in the Endpoint tab

Any override plan rate limits that have been added to your API for individual operations are not displayed in the API Endpoint tab in the UI. Only the plan rate limit is displayed.

A Product republish, with the Preserve Subscriptions option, fails after a consumer organization group has been removed from the visibility settings

If you remove a consumer organization group from the custom visibility settings for a Product, and that group contains a consumer organization with an application that is subscribed to the Product, an attempt to republish the Product with the Preserve Subscriptions option will fail even if that consumer organization is then added to the custom visibility settings individually.

Pagination setting is global across the API Connect user interfaces

If you set the Items per page value on any page in the API Manager user interface, that setting is then applied to all pages in both user interfaces in the same browser session. If you want to set the value separately for a specific page, open it in a private browser window. Such a setting in a private browser window is specific to that window and is lost when the window is closed.

Logging in to the API Connect user interfaces fails when using the Safari web browser

If you are using the Safari web browser and a Basic Authorization header exists for the same DNS domain in which API Connect is running, attempts to log in to the API Connect user interfaces, or to sign up by using an activation link, fail. To avoid this problem, use an alternative web browser.

Login to the API Manager user interface might fail with error 431 if the browser has a large number of cookies

Attempts to login to the API Manager user interface might fail if the HTTP header or cookie size is larger than 32 KB, a limitation that is imposed for security reasons. To resolve this problem, either clear the browser cache and cookies, or open a private window, then retry.

Numerical Handling in YAML Configurations and Precision Constraints in API Manager UI

• In the API Manager UI YAML configurations, numbers in exponential notation (for example 1e20) are handled differently based on their exponent value. Numbers with an exponent less than or equal to 20 are converted to their full integer form (for example 1e20 becomes 100,000,000,000,000,000,000) for display and processing. Numbers with an exponent greater than 20 stay in exponential notation (for example 1e21). Numbers that exceed the range of integers that are supported by DataPower JSON schema validation (-9,007,199,254,740,992 to 9,007,199,254,740,992) result in validation errors or unexpected behavior.
• JavaScript's inherent precision limitations truncate floating-point numbers to approximately 17 significant digits. For example:
  • Input: 0.123456789012345678901234567890
  • Processed Value: 0.12345678901234568

User interfaces are not supported in Microsoft Edge

The API Manager and Cloud Manager user interfaces are not supported in the Microsoft Edge web browser. To work in the user interfaces, use a different browser.