Known limitations

Analytics

Instana AutoTrace and Dynatrace injection are not supported in certain subsystems

Instana AutoTrace and Dynatrace injection are not supported in the Management, Analytics, CMS Portal, or Gateway subsystems. Do not use these features in these subsystems because they 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

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.

Consumer organization details are missing from the analytics event records generated by the webMethods API Gateway

Analytics event records generated by the webMethods API Gateway do not include consumer organization information. The developer_org_id field, which is intended to identify the consumer organization, is not populated in the event record. As a result, analytics reports cannot filter or group events by consumer organization.

Analytics for webMethods API Gateway APIs are not visible on the Developer Portal

Runtime analytics generated for webMethods API Gateway APIs are not displayed on the Developer Portal, even though the analytics data is collected and available in API Manager.

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

An OAuth provider fails if the resources that it references are not 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.

Truststore and keystore settings in a shared TLS client profile are not reflected in API Manager

If you create a shared TLS client profile in the Cloud Manager user interface and assign a truststore and a keystore, these truststore and keystore settings are not reflected in that TLS client profile in the API Manager user interface and cannot be set there. Furthermore, the TLS client profile list views display the value shared for the truststore and keystore rather than the correct values. To work around this problem, create the truststore, keystore, and TLS client profile separately for each provider organization in the API Manager user interface, then enable the TLS client profile in your Catalogs as required.

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.

Published assets appear in an incorrect state after restore

After performing a restore operation, some published assets might not return to the correct state within the gateway. As a result, the affected assets fail to invoke successfully even though the status appear as Published in the user interface. Restart the wmgateway‑apic‑proxy pod to ensure that the restored state is fully synchronized with the gateway.

Updating an application after its subscribed product is retired or deleted fails with HTTP 404

Attempting to update an application (add or edit APIs) fails with HTTP 404 after its subscribed product is retired or deleted. Delete the existing application and create a new application as follows:

1. Load the sample API into the API studio.
2. Publish the sample API to a catalog.
3. Create an application.
4. Add APIs to the application.

Teams API access control and visibility issue with standalone APIs

When a standalone API is added to a team, only the stub product is added to the team, not the API itself. As a result, API-level access control and visibility do not work as intended for standalone APIs when used with teams. As a workaround, configure team permissions at the product level instead of relying on API-level access controls. For more information about teams, see Adding teams to your provider organization.

Team visibility limitation for applications in catalogs

In this release, the UI does not yet support configuring team visibility for applications in catalogs. Backend support for application team visibility was delivered in 12.1.1.0, but the corresponding UI changes are targeted for 12.1.1.2. Existing team visibility support for Products and APIs that is related to default-admin-team remains available; however, users cannot configure application team visibility through the UI until the 12.1.1.2 release. For more information about teams, see Adding teams to your provider organization.

Cloud Manager

Adding members to a provider organization might fail

When adding members to a provider organization, the Cloud Manager user interface lists the current owner and members as well. If existing members are selected, the add action will fail.

Cloud Pak for Integration

Cannot add an API to the Asset Repository

If you are using API Connect as a component of Cloud Pak for Integration, you cannot add an API to the Asset Repository from API Connect.

Problem importing from Asset repository when user remains inactive

If there is no user activity on the page while importing an API from the Cloud Pak for Integration Asset repository, the user might see the following error: could not add asset, parent window missing

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

Configuration update mistakes cause admission webhook errors in OpenShift and Cloud Pak for Integration

In OpenShift and Cloud Pak for Integration, configuration update errors can cause the APIConnectCluster instance to go into the Pending state with an underlying component throwing an admission webhook error.

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

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

Gateway services that span data centers

If you want to configure a gateway service that consists of gateways in different data centers, then note the following points:

• This configuration should be used only if TMS is required and an external OAuth provider cannot be used.
• Network latency between sites must be less than 30 ms.
• For the analytics service to span data centers, network latency between data centers must be less than 10 ms. If you want to associate an analytics service with your gateway service, and cannot meet this latency requirement, then choose one of the data centers to host the analytics service.

Gateway timeout when validating very large API documents with the API governance service

If you are validating very large API documents (5 MB, or 100,000 lines, or more), with all of the rulesets selected by default, the API governance service is likely to take longer than 60 seconds to run, and this can result in an HTTP 504 gateway timeout. To workaround this issue, you can take the following actions:

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

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.

Parse policy limitation

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

Draft APIs (with v5c gateway) copied to API Studio fails to publish

After upgrading to APIC v12.1.0.1, draft APIs that use the DataPower Gateway (v5 compatible) and are copied into API Studio projects, cannot be published because the required policy definition files are not automatically created.

To publish the draft API successfully, complete the following steps.

1. For each API specification yaml file in the project, use the API Studio editor to create a new policy definition file <api_name>_policy.yaml as follows:

   kind: DataPowerAssembly
   apiVersion: api.ibm.com/v1
   metadata:
     name: <apiname>_policy
     namespace: <project>
     version: '1.0'
     tags: []
     labels:
       gatewayTypes:
         - datapower-v5
   spec:
     x-ibm-configuration:

2. Copy the x-ibm-configuration section from the API specification into the new file.
3. In the spec section of the API kind yaml file, add the following entry to reference the policy:

   policy-sequence:
     - $ref: <namespace>:<apiname>_policy:1.0
   

CORS policy created with the wildcard (*) in allowOrigins triggers a warning and causes publish errors

When a CORS policy includes the wildcard (*) in the allowOrigins field, the published asset shows a warning. The allowOrigins field must contain one or more specific origins. Any origin that contains a (*), or consists solely of (*), results in a publish error on the DataPower API Gateway. In addition to the warning during publish, an origin defined with (*) will not match any incoming request Origin.

DataPower Nano Gateway

Unsupported policy fields: title and telemetry

The title and telemetry fields in policy configurations are currently unsupported. While present in the schema, they are ignored during processing, and API Studio does not allow configuration. Any values provided for these fields are disregarded.

JSON schema validation of assemblies

The Operator and Runtime do not fully validate assemblies against the JSON schema. While most invalid configurations are rejected at startup, schema-level constraints (such as minimum/maximum ranges or regex validations) are not enforced.

Unsupported extra fields in policy configuration

Extra fields in a policy configuration are not supported. If additional fields are added beyond the recognized fields, the configuration might not work as expected. To avoid compatibility issues, do not include any fields that are not documented as supported. These extra fields might not cause a failure and will change in a future release when strict validation is enforced.

Unsupported localOnly database configuration for rate limit service with multiple gateway replicas

When multiple gateway replicas are used, do not configure the rate limit service with a localOnly database. A localOnly database applies limits per replica because replicas do not share data. To enforce limits across all replicas, use a database configuration that relies on an external datastore instead of localOnly.

Ingress limitation: TLS passthrough and certificate requirements

Nano gateway ingress does not support TLS passthrough with wildcard SNI hostnames when using ingress-nginx. To ensure proper functionality, the certificate used for nano gateway must include either a Common Name (CN) or a Subject Alternative Name (SAN) that matches the wildcard endpoint. Dynamic hostname assignment will not work without updating the ingress configuration for each new hostname, and failure to meet this requirement will result in the default Kubernetes ingress certificate being returned, causing invalid certificate errors.

Analytics collector accepting only traces signal

If APIC Analytics is the only server to which the Analytics Collector is configured to forward data (this is the default configuration), then the Analytics Collector will only accept the traces signal.

TLS Server Profile keystore containing a certificate chain causes nanogw to require mTLS

If the TLS Server Profile keystore configured for the Nano Gateway contains a full certificate chain (for example, the fullchain.pem certbot generates for lets encrypt cert), the entire chain is passed to the ca.crt value in the server profile secret in Kubernetes. As a result, the Nano Gateway service interprets this configuration as requiring mutual TLS for communication. Using the same certificate without the certificate chain does not trigger this behavior.

$telemetry function limitation for OpenTelemetry configuration attributes

DataPower Nano Gateway does not support retrieving the following fields using the $telemetry function when specified via OpenTelemetry configuration:

• catalog_id
• catalog_name
• gateway_service_name
• org_id
• org_name
• product_id
• product_name
• product_title
• product_version

For more information, see Built-in JSONata functions supported by DataPower Nano Gateway.

webMethods API Gateway

Ports

• HTTPS. v12.1 supports only port 5543. You cannot change this port.
• HTTP 5555. To enable HTTP connections on port 5555, an additional configuration, httpEnabled: true must be added during deployment.
• Default HTTP UI port and run time are not supported.
• Custom ports. Not supported.

  If you have customized default ports in v11.1, you cannot restore those custom values in v12.1 after transfer.

Load balancer

• If you have not configured the load balancer endpoint in API Gateway v11.1, the Gateway endpoint changes after data transfer. After transfer, verify connections to Developer Portal and Federated API Management in the Destinations page, and re‑publish as needed.
• If you have configured an external load balancer in API Gateway v11.1, the Gateway endpoint remains the same after v12.1 data transfer.

Event model changes after transferring analytics data

• API Gateway v12.1 publishes the following events to the Analytics service: Transactional events, Monitor events, and Threat protection events.
• Policy violation and error events are combined into transactional events in v12.1.
• v12.1 does not support the following v11.1 events:
  • Lifecycle events
  • Performance metrics
• API Gateway event field names have changed in v12.1. For details on the mapping of API Gateway v11.1 events with v12.1 field names, see the Mapping of v11.1 and v12.1 API Gateway events. .
• API Gateway batches events every 10 seconds and each batch (API event record) must not exceed 19 MB. The Analytics service rejects any record larger than this limit. The batching limits cannot be changed.
• Audit log. webMethods API Gateway writes the audit logging data to the Audit events dashboard in Cloud Manager. To view and download the audit events, go to Cloud Manager, and select Audit events.
• Analytics event record. Analytics event record for transactional events does not have the developer_org_id field populated with the consumer org of the application identified in runtime. Therefore you cannot see the consumer org details of the application identified in analytics event. You can manually check the consumer org of the application identified with the application name, which is available in the event.

Deployment configurations

• Installer and docker container based deployment is not supported.
• Paired deployment is replaced with combining a web application firewall (WAF) with an API Gateway that runs threat protection policies in combination with the API definitions.
• The externalized property files are not supported in v12.1. Instead, you must specify API Gateway deployment configurations using environment variables only.
• webMethods API Gateway can be configured in only one catalog in the whole API Connect system.

Promotion management

After data transition, you can use the Promotion management capability in webMethods API Gateway to promote data from v11.1 to v12.1. After phase 2 (management plane transition), promotion management capability is not currently available in v12.1 for API Manager-managed assets.

Publishing assets

Higher version of Developer Portal (v12.1) supports the lower version of API Gateway (v11.1). You can publish assets from Gateway v11.1 to Developer Portal v12.1 and use this path to verify communication after data transfer.

Global policy publishing limitation

Global policies cannot be published to WebMethods Gateway. When you publish a project containing a global policy to a catalog with a WebMethods Gateway configured, the project publishes to the catalog successfully, but the gateway proxy fails to send the global policy to the gateway. You will see the gateway processing status as high with an error indicating the failure.

To resolve this issue:

• Delete the global policy from the catalog.
• Publish a valid project (without the global policy) to clear the gateway processing status.

This limitation will be addressed in a future release. As a workaround, apply policies directly at the API level instead of using global policies when working with WebMethods Gateway.

Functionalities not supported

The following functionalities are not supported in v12.1.

• Paired deployments
• AppMesh functionality
• Microgateway management
• Accessibility profile

From the Administration page, the following functionalities are not supported:

• Cache configuration
• Application logs > Downloading log
• Application logs > fluentd
• Destination configuration > Transaction logger
• Manage Data > Archive purge and restore
• System Settings > Configuration
• Security > Ports
• Master Password
• Clustering

CMS Portal

Customized application view is reset to the default after upgrade if forums are also disabled

When upgrading API Connect version 10.0.5.0 or earlier to version 10.0.5.1 or later, if you have disabled forums on your CMS Portal site, and you have customized the application view, the customized application view will be reset to the default after the upgrade. To work around this issue, you can save the customized application view before running the upgrade, and then import the view into the upgraded CMS Portal.

To save the customized application view, run the following commands:

mkdir /tmp/tmp_config_<site-alias>
drush @<site-alias> config-get views.view.applications > /tmp/tmp_config_<site-alias>/views.view.applications.yaml

Where <site-alias> is the alias of your CMS Portal site.

To import the saved view after the upgrade, put the views.view.applications.yaml file inside a directory where it's the only file, and then run the following command:

drush @<site-alias> config-import --partial --source=/tmp/tmp_config_<site-alias>/

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 use the 'Lax' SameSite cookie attribute.

OpenAPI 3.1 validation errors in CMS Portal test tool

Some OpenAPI 3.1.x APIs might display a validation error when using the API test tool in the CMS Portal. This issue does not impact API functionality or runtime behavior. The validation error can be safely ignored, and APIs will work normally when invoked. You can use external API testing tools or invoke the API directly from your application.

Consumer Catalog

Consumer Catalog invitation sign-up fails for invited users

In the Consumer Catalog My Organization page, the member invitation flow does not work as expected. When an invited user attempts to sign up, the sign-up form submission fails.

Platform

No Analytics data available after ingress or external certificate rotation for Nano Gateway

After you rotate the ingress issuer certificate or external TLS certificates in environments that use the Nano Gateway, the Analytics collector might stop sending data to the Analytics service. The certificate rotation invalidates the secure connection that the Analytics collector uses, which prevents the collector from forwarding event data. As a result, Analytics dashboards might display missing, stale, or no data.

Manually restart the Analytics collector pod after the ingress issuer certificate is rotated. The pod restart reestablishes the secure connection and restores data flow.

New ibm-apiconnect-operator pod fails to start due existing terminating ibm-apiconnect-operator pod holding lock

The IBM APIConnect operator uses leader election (leader-for-life) to ensure that only one operator/controller pod is running/active at a time. This relies on Kubernetes garbage collection to clean up the lock when the old operator pod is deleted. The new ibm-apiconnect operator pod fails to start if an existing terminating ibm-apiconnect operator pod is still holding the lock.

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

Sometimes the completion of an SFTP restore on the Management subsystem does not restore the actual data

There is a known issue where sometimes a restore from the Management subsystem's SFTP backup succeeds but the data is not restored. If this happens, run the restore again.

New gateways cannot connect to existing gateways after the gateway peering certificates are changed

Changing the gateway peering SSL certificates after gateway installation causes new gateways to be unable to connect to existing gateways, resulting in an outage. A full restart of the gateway StatefulSet (by deleting all the StatefulSet pods) is required for the gateways to come back online.

Kubernetes might excessively evict pods

In Kubernetes, if insufficient memory, CPU, or storage resources are provided then pods are evicted randomly. To avoid this problem, allocate sufficient resources to the pods. In addition, there are known issues with log rotation in Kubernetes that are documented here: https://github.com/kubernetes/kubernetes/issues/59902. The lack of log rotation can cause logs to grow, limited only by the amount of storage on the node, eventually causing pods to restart. Therefore ensure that appropriate log levels are configured for all API Connect components.

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

Requests that take longer than the value of the nginx timeout cause a 409 error

Requests that take longer than the value of the nginx timeout can cause a 409 error, such as:

Another request is operating on portal-subsystem-03729230-4df7-4419-94c9-e7691b616382 with the same name, 
please try again.

The error occurs because the ingress controller is sending a repeat request when the previous one timed out. Your request will still continue processing in the background.

Setting resource limits in Kubernetes can cause containers to behave oddly at run time

In Kubernetes, you can set resource limits for each container. However, limiting CPU means that the container processes might slow down if they try to use too much. Limiting memory means that the Kubernetes code kills processes that try to allocate memory that would take the container over its limit. These limits can result in odd behavior such as the containers continually trying to start a daemon process, such as nginx or node, and exiting with success immediately.

When scaling down a Kubernetes cluster of DataPower gateways, the cluster might enter an unrecoverable state if the peering primary instance is lost

If you are scaling down a Kubernetes cluster of DataPower gateways, you must first complete the following steps to ensure that the peering primary instance is not lost:

1. List the pods in the cluster; for example:

   $ kubectl get pods -n apiconnect --selector app.kubernetes.io/component=datapower,crd.apiconnect.ibm.com/instance=gwv6
   NAME     READY   STATUS    RESTARTS   AGE
   gwv6-0   1/1     Running   0          3h31m
   gwv6-1   1/1     Running   0          3h32m
   gwv6-2   1/1     Running   0          3h34m

2. Enter the DataPower admin CLI for gateway 0, by entering the following command and logging in at the prompt; for example:

   $ kubectl attach -n apiconnect -it gwv6-0

3. Switch to the API Connect domain and enter config mode:

   idg# switch apiconnect
   idg[apiconnect]# config
   Global mode

4. Show the gateway peering status; for example:

   idg[apiconnect](config)# show gateway-peering-status
   
    Address        Configuration name Pending updates Replication offset Link status Primary
    -------------- ------------------ --------------- ------------------ ----------- -------
    1.2.3.1        gwd                0               18331896           ok          no
    1.2.3.1        rate-limit         0               3091219            ok          no
    1.2.3.1        subs               0               3150127            ok          no
    1.2.3.1        tms                0               3063575            ok          no
    1.2.3.2        gwd                0               18330948           ok          no
    1.2.3.2        rate-limit         0               3091067            ok          no
    1.2.3.2        subs               0               3149975            ok          no
    1.2.3.2        tms                0               3063257            ok          no
    1.2.3.3        gwd                0               18330948           ok          yes
    1.2.3.3        rate-limit         0               3091067            ok          yes
    1.2.3.3        subs               0               3149975            ok          yes
    1.2.3.3        tms                0               3063257            ok          yes

5. For each of the configuration names, set gateway 0 to be the peering primary instance:

   idg[apiconnect](config)# gateway-peering-switch-primary gwd
   The instance is now the primary in the peer group.
   idg[apiconnect](config)# gateway-peering-switch-primary rate-limit
   The instance is now the primary in the peer group.
   idg[apiconnect](config)# gateway-peering-switch-primary subs
   The instance is now the primary in the peer group.
   idg[apiconnect](config)# gateway-peering-switch-primary tms
   The instance is now the primary in the peer group.

6. Show the gateway peering status to confirm the changes; for example:

   idg[apiconnect](config)# show gateway-peering-status
   
    Address        Configuration name Pending updates Replication offset Link status Primary
    -------------- ------------------ --------------- ------------------ ----------- -------
    1.2.3.1        gwd                0               19067953           ok          yes
    1.2.3.1        rate-limit         0               3218172            ok          yes
    1.2.3.1        subs               0               3277032            ok          yes
    1.2.3.1        tms                0               3189160            ok          yes
    1.2.3.2        gwd                0               19067953           ok          no
    1.2.3.2        rate-limit         0               3218172            ok          no
    1.2.3.2        subs               0               3277200            ok          no
    1.2.3.2        tms                0               3189160            ok          no
    1.2.3.3        gwd                0               19069241           ok          no
    1.2.3.3        rate-limit         0               3218172            ok          no
    1.2.3.3        subs               0               3277508            ok          no
    1.2.3.3        tms                0               3189312            ok          no

Toolkit

Deleted security requirements might remain in the API source

Security requirements that are deleted from APIs in the IBM API Studio 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.

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.

No option to bulk delete APIs or Products

In the IBM API Studio 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 IBM API Studio 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 saved 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.

The apic cloud-settings:mail-server-configured command response is incorrect

If you use the apic cloud-settings:mail-server-configured without a --format parameter, it returns only the string MailServerConfigured rather than a boolean value to indicate whether an email server has been configured in the cloud settings. To retrieve the correct response, include the --format parameter, with a value of either yaml or json as required.

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 IBM API Studio 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.

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 IBM API Studio 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.

The apic cloud-settings:topology command doesn't return a topology object

If you use the apic cloud-settings:topology command without a --format parameter, it returns only the string CloudTopology rather than the cloud topology. To retrieve the topology object, include the --format parameter, with a value of either yaml or json as required.

User Interface

Publish failures after an upgrade

After you upgrade from API Connect 10.0.11, publishing to a catalog might fail for some products that were migrated from draft products to IBM API Studio.

When this issue occurs, the publish operation fails with an error similar to the following message:

Build validation failed. Error while publishing project: Duplicate asset detected:
'default_productname-product' in namespace 'project' with version '1.0.0' and kind 'Quota'.
First seen in file 'project/default_productname-product_plan_1.0.0.yaml'

This error occurs because the product plan and the quota use the same name. IBM API Studio requires these assets to have unique names. When the names are identical, a conflict occurs during the publish operation.

To resolve this issue, rename the product plan and update the corresponding reference in the product file.

• In IBM API Studio, locate the file that is identified in the error message (for example,project/default_productname-product_plan_1.0.0.yaml).
• Edit the file and update the metadata.name field so that the name ends with -plan. For example:

  name: default_productname-product-plan

• Open the product file that references the plan and update the plan reference to use the new name. For example, change:

  $ref: project:default_productname:1.0.0

  to:

  $ref: project:default_productname-plan:1.0.0

• After editing these files, you should be able to publish the product successfully.

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

Having a stale cache in your browser can result in unexpected behavior in the Cloud Manager and API Manager UI, such as fetch errors, incorrect data being displayed, and blank pages. To work around this issue, particularly if you have just upgraded your deployment, 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.

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 Cloud Manager or 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 Cloud Manager or API Manager user interfaces might fail with error 431 if the browser has a large number of cookies

Attempts to login to the Cloud Manager or API Manager user interfaces might fail if the HTTP header or cookie size is more 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.

IBM API Studio

API design and gateway capabilities

The following API design and Gateway capabilities are not supported:

• GraphQL API authoring. Authoring capabilities for GraphQL API are not available.
• Form view does not support WSDL files.
• IBM API Studio does not support testing published SOAP APIs in the Test or Try out options. This support is planned for a later release.
• DataPower Gateway (v5 compatible) SOAP support. SOAP API import sets datapower-api-gateway as the default gateway in the assembly configuration. SOAP API authoring on DataPower Gateway (v5 compatible) requires manual updates to the assembly configuration. Update the assembly-project-name.yml file and change the gateway value to datapower-gateway. Re-author all policies to use DataPower Gateway (v5 compatible) specific policies, as policies authored for datapower-api-gateway do not apply to SOAP APIs.
• Product import supports only product assets downloaded from v10 API Connect.
• Importing a v10 API Connect SOAP API and its associated product into standalone IBM API Studio does not retain the API-product association. Associate the API with the product after import.
• Updating an API with a specification that uses a different file extension leads to a file name mismatch. For example, if the current specification is in the .json format and you update it with a .yml file or vice versa, the issue occurs. Hence, if you click the API specification path in the code view then an error message appears.

  To resolve this issue, manually update the API specification path in the API file to match the actual filename created.

• Import fails when a plan and a ratelimit/quota policy use the same name. The duplicate names cause a project file name conflict and prevent the product from being imported.

  Workaround: Use unique names for plans and ratelimit/quota policies before importing the product.

Error during API specification update

Updating an API with a specification that uses a different file extension leads to a file name mismatch. For example, if the current specification is in the .json format and you update it with a .yml file or vice versa, the issue occurs. Hence, if you click the API specification path in the code view then the 'Reference file not found' error message appears. Also, the API cannot be published.

To resolve this issue, manually update the API specification path in the API file to match the actual filename created.

Product management

The following product management capabilities are not supported:

• Automatic publishing. Publishing a product automatically to the catalog for testing is not available.
• Visibility and subscription control. Fine-grained visibility and subscription controls cannot be set during publishing. These controls are available during product authoring only.

Asset handling

Asset uniqueness. Each asset must have a unique namespace:name:version combination to avoid conflicts and maintain consistency.

Additional considerations

• Analytics for DataPower Nano Gateway APIs. DataPower Nano Gateway does not log analytics for runtime invocations unless security policies are explicitly added. Configure security policies to enable logging of runtime transactions.
• Operation selection in policies. In policies such as Operation Switch and Validate, operation selection does not automatically read information from the API specification. Add the operation details manually in code view.
• Publishing projects to the APIM Catalog. On Linux, the Desktop application does not allow publishing projects to the APIM Catalog. To work around this issue, use IBM API Studio available in API Connect or use the Desktop application on Windows or macOS.

Validate policy fails in assembly canvas for DataPower v5 gateway

When creating an API for the DataPower Gateway (v5 compatible), using the Validate action on a Validate policy in the assembly canvas can result in an error. This issue occurs only in the visual assembly editor and does not affect the ability to configure or use the Validate policy. To avoid this error, configure the Validate policy directly in the assembly source view instead of using the assembly canvas.

User-defined policies are not supported

IBM API Studio does not support the user-defined policies that are supported in the earlier versions of DataPower Gateway (v5 compatible) and DataPower Nano Gateway.

Federated API Management

Limitation on setting intervals

A known issue exists with the metrics interval configuration for DataPower API Gateway (v6) and DataPower Nano Gateway. If the metrics interval is not set to 300 seconds, the reported metrics will be inaccurate. Another known issue is that the heartbeat interval settings for these gateways do not update after the initial configuration made when federated API management is first registered with Cloud Manager. Subsequent changes to the interval are not sent to federated API management, hence not reflected in the federated API management.

Limitation on editing runtimes

For API Connect runtimes, the location cannot be configured during registration and must be set later using the Edit option in the federated API management UI. If federated API management settings are disabled in Cloud Manager, all API Connect runtimes integrated with federated API management are deleted, and any previously configured location values are lost. When the settings are re-enabled, the runtimes are re-registered, and the location must be configured again in the UI. Although API Connect runtimes can be edited in the federated API management, the value specified in Cloud Manager always takes precedence.

Important notes on asset ownership

Ownership of an asset is determined at the time of creation and is automatically assigned to the user whose credentials are used during the initial setup. The ownership remains associated with that user because the runtimes and APIs are registered at creation time. For example, if the initial configuration is performed using Administrator credentials, the runtimes and APIs are created with Administrator as the owner. If the credentials are later changed to another user, such as apicptechuser, the existing runtimes and APIs are not deleted or recreated. Since the assets are retained and only the credentials are updated, the ownership remains unchanged.

This behavior also applies when the authentication mode is changed (for example, from mTLS to Basic Auth). Because the existing runtimes and APIs continue to be reused and are not recreated, the ownership of the assets remains unchanged.

Limitation on sending heartbeat to federated API management

The DataPower API Gateway (v6) appliance on OVA does not support sending heartbeats to federated API Management. Consequently, the DataPower API Gateway status is displayed as red in the Federated API Management UI. This is an expected limitation and does not affect API discovery or metrics collection, which continue to function normally.

Limitation when registering runtimes

When you register API Connect runtimes with federated API Management using APIC CLI tool, the runtime might occasionally be duplicated in federated API Management.

Transfer Advisor

Header control with multiple values in allow list

The Transfer Advisor utility incorrectly identifies APIs as incompatible when the header-control allow list contains multiple values within an invoke policy. This issue affects Version 12.1.1.0 and will be resolved in version 12.1.1.2.

When an API definition includes an invoke policy with header-control settings that have multiple values defined in the allow list, the Transfer Advisor compatibility check incorrectly returns the API as "Not Compatible". This occurs because the utility does not properly process array lists in the header-control configuration.

Important: This limitation also potentially affects:

• Header-control block list with multiple values
• Parameter-control allow list and block list with multiple values

There is currently no CLI-based workaround to mitigate the header-control issue. The only available workaround is to create a nano portability project with the non-compatible API through backend methods (this option is not available through the UI). However, this workaround does not resolve the actual compatibility issue and requires deploying the Transfer Advisor Rust utility fix to fully address the problem.

Restriction: Creating nano portability projects for APIs marked as incompatible is not supported through the user interface and should only be attempted with proper understanding of the limitations.

Customers using APIs with multiple values in header-control allow lists will be unable to use the Transfer Advisor feature through the standard workflow until the fix is deployed. Until the fix is available:

• Review your API definitions to identify if they use multiple values in header-control allow lists
• Consider temporarily modifying header-control configurations to use single values if possible
• Wait for the official fix in version 12.1.1.2 (on-premises)
• Contact support if you need assistance with critical APIs affected by this limitation