Known limitations

To resolve this issue, we have released v10.0.8.2-ifix1 as a full installation image.

• New deployments: Perform a fresh installation using v10.0.8.2-ifix1 to avoid encountering this issue.
• Existing deployments: If you have already upgraded to v10.0.8.2 and are experiencing this problem, upgrade directly to v10.0.8.2-ifix1 ( a complete replacement, not an incremental patch). If you have not yet upgraded to 10.0.8.2 then upgrade directly to v10.0.8.2-ifix1.

Before upgrading to APIC v10.0.8.2-ifix1, you must run the apicops preupgrade command to check for:

• Recent encryption-related issues
• Invalid gateway-extensions

For detailed upgrade or installation steps, refer to the IBM documentation.

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.

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.

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.

$ kubectl get pods -n <namespace>
NAME                                                       READY   STATUS      RESTARTS      AGE
...
gwv6-0                                                       1/1     Running     0            1h
gwv6-1                                                       1/1     Running     0            1h
gwv6-2                                                       0/1     Running     0            1h
...

To work around this behavior, use the following command delete the pod that is not ready:

$ kubectl delete pod gwv6-2 -n <namespace> 

If there are multiple gateway pods in the cluster, the delete operation will not result in any service disruption.

Work around the issue by reloading the Import API page and then opening the Asset repository again.

1. Download and extract API Designer, then install the credentials file as explained in steps 1, 2, and 6 in Installing the toolkit.

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).

• Validate the API document by using only one ruleset at a time.
• Increase your component deployment profile, for example to a three replica profile. For more information, see Deployment and component profiles, and Planning your deployment topology and profiles on VMware.

If you suspect you are encountering this issue, verify it by running the following command:

kubectl -n <namespace> logs <new-ibm-apiconnect-pod-name> | grep "LockOwner"

If the lock is the problem, the log contains a message similar to the following example:

existing lock","LockOwner":"ibm-apiconnect-xxxxxx held by terminating pod

Resolve the issue by completing one of the following options:

• Force delete the terminating pod by running the following command:

  kubectl -n <namespace> delete pod <terminating-ibm-apiconnect-pod-name> --force --grace-period=0

  Kubernetes deletes the lock when the pod is deleted.

• Remove the lock manually by running the following command:

  kubectl delete cm ibm-apiconnect-lock

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.

• 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.

• 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.

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

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

• clustermgmt:getNodesHotThreads
• clustermgmt:getNodesHotThreadsById

oc get apiconnectcluster -n APIC_namespace

NAME   READY  STATUS    VERSION             RECONCILED VERSION   AGE
m1     admission webhook "vmanagementcluster.kb.io" denied the request: ManagementCluster.management.apiconnect.example.com "m1-mgmt" is invalid: [spec.databaseBackup.restartDB.accept: Invalid value: false: databaseBackup protocol has changed (from '' to 'objstore') and requires database restart. accept restartDB to restart database, spec.databaseBackup.restartDB.accept: Invalid value: false: databaseBackup configuration has changed and requires database restart. accept restartDB to restart database]   Pending   10.0.1.5-3388-eus   10.0.1.5-3388-eus    2d6h

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

• 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.

• 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.

- 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)

Cannot read property 'type' of null

To resolve this problem, remove any invalid OpenAPI YAML files from the startup directory, then restart the API Designer user interface.

• 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.

You may also follow the instructions described here https://success.docker.com/article/how-to-setup-log-rotation-post-installation to set the maximum size of the log before it is rolled (max-size) and the maximum number of log files that can be present (max-files). More information about the Docker JSON File logging driver is available here: https://docs.docker.com/config/containers/logging/json-file/.

The changing of endpoints with APICUP after they have been configured in Cloud Manager is not supported. Any such endpoint changes will not be propagated to a running deployment.

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.

• 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