API Gateway and API Manager 7.7 January 2020 Release Notes

20 minute read

Summary

API Gateway is available as a software installation or a virtualized deployment in Docker containers. API Manager is a licensed product running on top of API Gateway, and has the same deployment options as API Gateway.

The software installation is available on Linux. For more details on supported platforms for software installation, see System requirements.

Docker deployment is supported on Linux. For a summary of the system requirements for a Docker deployment, see Set up Docker environment.

New features and enhancements

The following new features and enhancements are available in this release.

Swagger 2.0 enhancements

API Manager imports, retains, and exports all Swagger v2.0 fields, except for vendor extensions.

Open API Specification (OAS) 3.0 enhancements

  • API Manager imports, retains, and exports all Open API Specification (OAS) v3.0 fields, except for vendor extensions, callbacks, links, and examples.
  • Parameter content types are supported in OAS3.

Try it improvements

In API Manager, the Try it and Try method capabilities support the rendering of enum, which allows you to send multipart forms.

  • When trying the method of an API, you can select files as part of the request.
  • The parameters object types are autogenerated in the UI, and nested schemes and arrays are rendered fully.
  • The default for parameters are fully supported.
  • The allOf and anyOf in the request bodies are also supported.

Usage tracking improvements

Health checks are no longer counted in usage tracking.

Two new environment variables have been introduced:

  • EMT_HEALTHCHECK_PORT (allowable range 1025 to 65535 inclusive)
  • EMT_HEALTHCHECK_PATH (a path that begins with / character and includes 0 or more characters)

Both of these environment variables are optional and configurable with defaults of 8080 and /healthcheck. The endpoint configured here is not billed as part of usage tracking.

Back-end API improvements

The API Manager UI supports OAS3 response.content.schemes.

  • The OAS3 multiple back-ends are rendered on the screen, which allows you to select the required URL.
  • The UI has been extended to include all response codes available in OAS3.
  • Multipart request bodies are rendered in the back-end UI.
  • The UI allows you to define allOf response types for Swagger 2.
  • The DataTypes in API Manager have been changed to align with the OAS3 data types.
  • You have the option to modify all back-end APIs without cloning.

API documentation enhancements

All API Manager APIs are represented as both Swagger 2 and OAS3 (previously these APIs were only available in Swagger 2 format).

Traffic monitor externalization showcase

An example dashboard for Elasticsearch leverages existing capabilities to output traffic monitor data using the open logging functionality and showcases this capability.

Easy to integrate with and to set up, ELK enables you to extend your analytics needs using easy customization options.

The showcase provides a HTML version of the Traffic Monitor dashboard to visualize data, while demonstrating how you can leverage ELK to increase performance and storage capacity.

Multi organization beta

A new beta version (1.4) version of the following APIs are shipped with this release.

  • The user API facilitates the GET, POST, UPDATE, and DELETE of additional organizations and roles.
  • The currentuser API is used by API Manager and returns the organizations and role information as part of a validation check.
  • The apirepo API encapsulates all of the actions that can be performed to manage a back-end API in API Manager. You can pass in an organizationId={uuid} to filter by organization, or specify no {uuid} to return all of the back-end APIs for all organizations that the user is a member of.
  • The discovery API manages all APIs in the API Catalog and all virtualized front-end APIs. This API also provides the ability to return all APIs associated with a user, or to filter by an organizationId={uuid}.

These APIs manage two new variables, the orgs2Role and orgs2Name maps. The user is still assigned to a primary organization as in earlier versions, however, the new variables store additional organizations and the user’s role within each organization.

The beta 1.4 version of the APIs are generated in OAS3 format and published on the Product APIs page on the Axway Documentation portal.

To enable the 1.4 beta APIs in Policy Studio, browse to the API Portal v1.4 Servlet and set the com.axway.portal.servlet.disabled flag to false.

Important changes

It is important, especially when upgrading from an earlier version, to be aware of the following changes in the behavior or operation of the product in this release.

Increased validation of WSDLs

The Xerces library has been updated to xerces 2.12.0. This library enforces stricter rules when validating malformed schemas. This means that some WSDLs that were previously imported successfully by API Manager might not import successfully in this version.

To suppress schema validation errors and relax the stricter validation of XML files, set the flag -DwsdlImport.suppressSchemaValidationErrors to true in the policystudio.ini file. The default value is false.

Filebeat v6.2.2

Filebeat has been updated to use v6.2.2. Before installing this update, you must delete the Filebeat folder /apigateway/tools/filebeat-5.2.0. When using Filebeat, follow the official Filebeat documentation.

Increased validation of /users endpoint

In earlier versions of API Manager, the /users API returns a list of all the users in an organization. This endpoint allowed a user to share an application with other users in their organization. This was identified as a security risk, as only organization administrators and API administrators should have access to a list of users, and not user roles. The ability for user roles to view all other user names in the organization has been removed. This change might break some use cases for API Manager and API Portal.

To reduce the impact of this change, you can relax this restriction using a configuration flag. Set the flag in the jvm.xml file (it does not exist by default) under groups/group-x/instance-y/conf.

<ConfigurationFragment>
    <VMArg name="-DAPIGW_TOGGLE_FEATURE_GET_ALL_USERS=true" />
</ConfigurationFragment>

OpenJDK JRE

API Gateway and API Manager 7.7 and later support OpenJDK JRE, and this update includes Zulu OpenJDK 1.8 JRE instead of Oracle JRE 1.8.

API Gateway behavior

Anonymous cipher suites

The JRE included in API Gateway disables undesirable cipher suites when using SSL/TLS by default. Users using RSA Access Manager (formerly known as RSA ClearTrust) with API Gateway might experience SSL/TLS handshake issues where no common cipher suites can be found. In this case, you should reconfigure SSL/TLS of the RSA Access Manager to support stronger cipher suites.

Alternatively, to re-enable the anonymous cipher suites in JRE for successful SSL/TLS connections with the RSA Access Manager, remove anon from the jdk.tls.disabledAlgorithms Java security property in the INSTALL_DIR/Linux.x86_64/jre/lib/security/java.security file.

Endpoint identification property

The JRE included in API Gateway enables endpoint identification algorithms for LDAPS (secure LDAP over TLS) by default to improve the robustness of the connections. This might cause API Gateway LDAP filters to fail to connect to an LDAPS server. To disable endpoint identification add the <VMArg name="-Dcom.sun.jndi.ldap.object.disableEndpointIdentification=true"/> line to the INSTALL_DIR/system/conf/jvm.xml file.

API Manager behavior

Trailing slash property

An inbound API request with a trailing slash can match an API path with no trailing slash. To activate this feature set the Java property com.vordel.apimanager.uri.path.trailingSlash.preserve to true. The default value is false.

Content type property

An API method’s Content-Type is checked against the API method’s defined MIME type when performing path matching. To allow legacy API method matching and disable this check, set the Java property com.coreapireg.apimethod.contenttype.legacy to true. The default value is false.

Caching property

Enable caching to improve general system performance and speed. Set the com.axway.apimanager.api.data.cache Java system property to true. External clients, API keys, and OAuth credentials cache are optimized so that updates to the cache no longer block API Manager runtime traffic, resulting in performance improvements for corresponding API Manager APIs. As a result of the non-blocking cache updates, API Manager memory consumption will increase, particularly in systems with large numbers of external clients, API keys or OAuth credentials.

No match property

To configure the status code of an unsuccessful match of an API to 404 when authentication is successful, set the Java property com.axway.apimanager.use404AuthSuccessNoMatch to true. The default value is false.

MIME types

To import API Gateway Management API Swagger into API Manager API Catalog, you must add the application/x-download MIME type to the default list of MIME types in API Gateway. Select Server Settings > General > Mime configuration in the Policy Studio tree and add application/x-download to the MIME list. After the configuration is deployed to API Gateway, you can import the API Gateway Manager API Swagger into API Manager API Catalog.

Confidential fields property

Fields that contain confidential information are no longer returned in some API calls. For example, a call to GET /api/portal/v1.3/proxies/ does not return the password in the AuthenticationProfile.parameters\["password"] field. For compatibility with earlier versions, you can continue to return confidential fields. Set the system property com.axway.apimanager.api.model.disable.confidential.fields to true in the jvm.xml file (it does not exist by default) under groups/group-x/instance-y/conf.

<ConfigurationFragment>
    <VMArg name="-Dcom.axway.apimanager.api.model.disable.confidential.fields=true"/>
</ConfigurationFragment>

Security

nosniff header

The X-Content-Type-Options HTTP header with value nosniff is not included in a HTTP response serving static content from the API Gateway or API Manager. This static content is served from the API Gateway or API Manager webapps directory. No dynamic content is served from the webapps directory. This means that there is no risk of the browser making an incorrect assumption of the content type and exposing a security vulnerability. The X-Content-Type-Options response header with the value nosniff is included with HTTP responses serving dynamic content by default.

CSRF check property

If you are using the API Manager Management APIs, Client Application Registry APIs, and API Gateway APIs you might need to disable the CSRF token check implemented in v7.5.3 SP9 and later. To disable this check, set the Java system property com.axway.apimanager.csrf to false. The default is true.

Custom filters

If you have written a custom filter using the extension kit, you might need to update your custom code as a result of changes in the classes.

The following interfaces deprecate _() and __() in favor of a new resolve() method:

  • com.vordel.client.manager.ResourceResolver
  • com.vordel.client.manager.attr.ScreenAttribute
  • com.vordel.client.manager.wizard.EntityContext

Both DefaultGUIFilter and VordelWizard classes do not implement the ResourceResolver interface. As a result, any classes extending either of these must replace _() and __() method calls with resolve().

Deprecated features

As part of our software development life cycle we constantly review our API Management offering.

The following capabilities have been deprecated.

Antivirus scanners

API Gateway already supports the industry standard Internet Content Adaption Protocol (ICAP). From the November 2020 release the following embedded antivirus scanners will be removed:

  • McAfee
  • Sophos
  • Clam AV

Content scanning is still supported using the ICAP filter, which provides out-of-the-box integration with ICAP-capable servers provided by Symantec, McAfee, OPSWAT and others, promoting ease of deployment and operational control.

Back-end API exports

Back-end API exports were designed to support the creation and maintenance of APIs using API Manager, and the functionality is based on the Swagger v1 format. API Manager now supports OAS3 and Swagger 2, meaning that this export functionality is outdated. In addition, a majority of customers store APIs in source control tools outside of API Manager. For these reasons, exporting back-end APIs will not be supported from 7.7.20200331 and later.

Back-end API exports will only be available for APIs created in API Manager, and not for imported APIs. Export of API collections and download from the API Catalog will continue to be fully supported.

Removed features

To stay current and align our offerings with customer demand and best practices, Axway might discontinue support for some capabilities. As part of this review, the following capabilities have been removed.

API Tester

For testing APIs, it is recommended to use alternative tools, such as Postman, SoapUI, or API Fortress.

RAML support

RESTful API Modeling Language (RAML) support has been removed in favour of widely-adopted standards like Swagger and OpenAPI 3.

Export of back-end APIs for OAS3 or WSDL

The functionality to export back-end APIs converts all API formats to Swagger 1. With the introduction of OAS3, API Manager uses the io.swagger.parser.v3.swagger-parser-v3:2.0.16 and io.swagger.swagger-parser:1.0.48 libraries during the import process. This means that the export of back-end APIs is not supported for OAS3 or WSDL APIs, as this functionality relied on custom code in the old parser that is no longer available.

Documentation PDF format

Documentation is no longer provided in PDF format. You can continue to save individual topics or entire guides in PDF format using the Save as PDF icon on the Axway documentation portal.

Fixed issues

This version of API Gateway and API Manager includes the fixes from all 7.5.3, 7.6.2, and 7.7 service packs or updates released prior to this version. For details of all the service pack fixes included, see corresponding SP Readme attached to each service pack on Axway Support.

Fixed security vulnerabilities

There are no fixed security vulnerabilities in this version.

Other fixed issues

Internal ID Case ID Description
RDAPI-18533 612543 01095012 01094618 Issue: Retrieve OAuth Client Access Token from Token Storage filter requires a hard-coded client credential profile. Resolution: This filter reads the client credential profile from the whiteboard in the same way as the Get OAuth Access Token filter.
RDAPI-18647 616503 01103775 01073101 Issue: XML redaction is very slow when processing large XML files. Resolution: XML redaction has been fully rewritten to increase performance and reduce the memory foot print. You can control the maximum memory size and the maximum acceptable XML nodes depth using the properties <XMLRedactor maxBufferSize="32768" maxDepth="1024">. Issue: XML redaction with disposition redactDescendants is only removing children nodes. Resolution: XML redaction correctly removes both text and children nodes.
RDAPI-18669 622369 01088090 Issue: Get OAuth Client Access Token filter does not handle array data on the JSON returned by the OAuth server. Resolution: The JSON can contain arrays as additional information.
RDAPI-18797 629370 01119493 01123904 01122491 01119522 Issue: API Gateway 7.7 does not allow underscores in API Manager back-end URLs as per RFC952. If you upgrade from an earlier version of API Gateway (which allowed underscores) and you are using underscores in the host name component of your back-end URLs, calls to these APIs will fail. Resolution: Set the new JVM property com.axway.apimanager.backend.url.validation.hostname.allowunderscore to true in the jvm.xml configuration to allow underscores in the host name part of an API Manager back-end URL.
RDAPI-18851 642983 01127663 Issue: Some APIs are not working after upgrade from 7.5.3 to 7.7 and logs show an error Unrecognized field "blob". Resolution: Field blob was added to 7.7 to match the 7.5.3 method definition.

Known issues

The following are known issues for this release.

Internal ID Description
RDAPI-13653 API Portal incorrect Content-Type for SOAP + empty model schema
RDAPI-14100 Update tuning recommendations for ‘High availability with local storage’ config
RDAPI-15607 Cannot access NodeManager after submitting external CA signed certs
RDAPI-15609 Cannot access NodeManager after submitting external CA signed certs
RDAPI-15669 Stored XSS in the application’s Oauth Redirect URL - Encode OAuth Redirect URLs on output
RDAPI-15671 Update trailing slash support in Jython scripts samples
RDAPI-15760 Request headers reflected as response headers
RDAPI-15781 Swagger Generation Tool - Duplicate paths are not reported
RDAPI-15981 Scopes fields for API Key remain visible even if Application Scopes are disabled
RDAPI-16330 Maven ‘clean’ on install/pom.xml does not cleanup install/system/lib
RDAPI-16486 Changes in the mapper always require a reload in the Execute Data Maps filter and once reloaded then providing values for the required parameters must be repeated
RDAPI-16576 Duplicate headers returned when calling API Gateway Rest API
RDAPI-16955 API Manager event poller unnecessarily locks cache updates from Cassandra
RDAPI-17041 Policy called as REST API in Policy Studio, and local fault handler not catching unhandled false return from policy called by policy shortcut
RDAPI-17208 Test and document upgrading Gateway and Cassandra (7.5.3->7.7.x / 2.2.8->2.2.12) to new hosts
RDAPI-17924 Error while upgrading JSON schema from 7.5.3 to 7.7 - Cannot set ESPK for non-reference type field
RDAPI-18082 Regression: Policy Shortcut filters no longer automatically renamed in 7.7
RDAPI-18123 Forgot password should force password change like first time login
RDAPI-18198 CORS preflight fails for WSDL based API Manager APIs, thus Try-It fails
RDAPI-18294 KPS REST API documentation missing info
RDAPI-18376 “you do not have permission to access this resource” when a user creates an application
RDAPI-18379 Spurious “forbidden” error in Manager UI
RDAPI-18473 Get OAuth Access Token filter is not accepting “aud” JWT claim
RDAPI-18485 “Get OAuth Access Token” expired token then refresh flow, not resetting message
RDAPI-18639 Information needed on “suppressed” CVEs reported against APIG 7.7.2
RDAPI-18674 Insufficient data validation when importing an Application
RDAPI-18737 Turning off “delegate user/application management” causes UI to break
RDAPI-18774 Nested relative path behavior changed, causing customer policies to fail
RDAPI-18776 regex for custom property in API Manager
RDAPI-18812 DB definition with wildcard password fails in Resource Owner Password Credential filter
RDAPI-18876 Extremely slow Swagger virtualization when Cassandra is under load

Update a classic (non-container) deployment

These instructions apply to API Gateway and API Manager classic deployments only. For container deployments, see Update a container deployment.

Prerequisites

This update has the following prerequisites in addition to the System requirements.

  1. Shut down any Node Manager or API Gateway instances on your existing installation.

  2. Back up your existing installation. For details on backing up, see API Gateway backup and disaster recovery. Ensure that you back up any customized files. You should merge updated files instead of copying them back directly to avoid any regex matching issues. For example, the following directories might contain customized files:

    webapps/apiportal/vordel/apiportal
    webapps/emc/vordel/manager/app
    webapps/emc
    system/conf/apiportal/email
    system/conf
    samples/scripts/
    tools/filebeat-VERSION-PLATFORM
    
  3. Remove old third-party libraries by deleting the following directories:

    INSTALL_DIR/apigateway/system/lib/modules
    INSTALL_DIR/analytics/system/lib/modules
    
  4. Remove old JRE versions by deleting the following directories:

    INSTALL_DIR/apigateway/platform/jre
    
  5. If you have an existing Apache Cassandra installation, ensure that you back up your data (Cassandra and kpsadmin), and that the JAVA_HOME variable is set correctly in cassandra.in.sh and cassandra.in.bat.

  6. Remove the old Filebeat folder /apigateway/tools/filebeat-5.2.0. Check any customized files to see if they are compatible with the new version. See Filebeat for more information.

  7. On Linux, remove existing capabilities on product binaries (which might prevent overwriting files):

    setcap -r INSTALL_DIR/apigateway/platform/bin/vshell
    

FIPS mode only

If FIPS mode is enabled, you must also perform the following steps to install the update:

  1. Run togglefips --disable to turn FIPS mode off.
  2. Start the Node Manager to move the JARs.
  3. Stop the Node Manager.
  4. Install the API Gateway update.
  5. Start the Node Manager.
  6. Stop the Node Manager.
  7. Run togglefips --enable to turn FIPS on again.
  8. Start the Node Manager.

Installation

This section describes how to install the update on existing 7.7 installations of API Gateway or API Manager.

  • If you have installed an existing version of API Manager, installing the API Gateway server update automatically also installs the updates and fixes for API Manager.
  • If you have installed a licensed version of API Gateway or API Manager 7.7, you do not require a new license to install updates.

Install the API Gateway server update

To install the update on your existing API Gateway 7.7 server installation, perform the following steps:

  1. Ensure that your existing API Gateway instance and Node Manager have been stopped.

  2. Remove any previous patches from your INSTALL_DIR/ext/lib and INSTALL_DIR/META-INF directories (or the ext/lib directory in an API Gateway instance). These patches have already been included in this update. You do not need to copy patches from a previous version.

  3. Verify the owners of API Gateway binaries before extracting the update.

    ls -l INSTALL_DIR/apigateway/posix/bin
    
  4. Using the same user who owns the API Gateway binaries, unzip and extract API Gateway 7.7 Update over the apigateway directory in your existing installation directory . For example:

    tar -xzvf APIGateway_7.7.YYYYMMDD_Core_linux-x86-64_BNnn.tar.gz -C /opt/Axway-7.7/apigateway/
    
  5. Change to the apigateway directory in your installation.

    cd INSTALL_DIR/apigateway
    
  6. Run the post-install script, and ensure that the correct permissions are set:

    apigw_sp_post_install.sh
    

Install the Policy Studio update

To install the update on your existing Policy Studio installation, perform the following steps:

  1. Shut down Policy Studio.

  2. Back up your existing INSTALL_DIR/policystudio directory.

  3. Remove old JRE versions by deleting the following directories:

    INSTALL_DIR/policystudio/jre
    
  4. Unzip and extract API Gateway 7.7 Policy Studio Update over the policystudio directory in your existing API Gateway 7.7 installation directory. For example:

    tar -xzvf APIGateway_7.7.YYYYMMDD_PolicyStudio_linux-x86-64_BNnn.tar.gz -C /opt/Axway-7.7/policystudio/
    
  5. Start Policy Studio with policystudio -clean

Install the Configuration Studio update

To install the update on your existing Configuration Studio installation, perform the following steps:

  1. Shut down Configuration Studio.

  2. Back up your existing INSTALL_DIR/configurationstudio directory.

  3. Remove old JRE versions by deleting the following directories:

    INSTALL_DIR/configurationstudio/jre
    
  4. Unzip and extract API Gateway 7.7 Configuration Studio Update over the configurationstudio directory in your existing API Gateway 7.7 installation directory. For example:

    tar -xzvf APIGateway_7.7.YYYYMMDD_ConfigurationStudio_linux-x86-64_BNnn.tar.gz -C /opt/Axway-7.7/configurationstudio/
    
  5. Start Configuration Studio with configurationstudio -clean

Install the API Gateway Analytics update

To install the update on your existing API Gateway Analytics 7.7 installation, perform the following steps:

  1. Ensure that your existing API Gateway Analytics instance and Node Manager have been stopped.

  2. Verify the owners of API Gateway binaries before extracting the update.

    ls -l INSTALL_DIR/analytics/posix/bin
    
  3. Using the same user who owns the API Gateway Analytics binaries, unzip and extract API Gateway 7.7 Analytics Update over the analytics directory in your existing API Gateway 7.7 installation directory. For example:

    tar -xzvf APIGateway_7.7.YYYYMMDD_Analytics_linux-x86-64_BNnn.tar.gz -C /opt/Axway-7.7/analytics/
    
  4. Change to the analytics directory in your installation:

    cd INSTALL_DIR/analytics
    
  5. Run the post-install script for API Gateway Analytics.

    apigw_analytics_sp_post_install.sh
    

You must also install an update for your existing API Gateway 7.7 server.

After installation

The following steps apply after installing the update.

API Gateway

To allow an unprivileged user to run the API Gateway on a Linux system, perform the following steps:

  1. Add the following line to the INSTALL_DIR/system/conf/jvm.xml file:

    <VMArg name="-Djava.library.path=$VDISTDIR/$DISTRIBUTION/jre/lib/amd64/server:$VDISTDIR/$DISTRIBUTION/jre/lib/amd64:$VDISTDIR/$DISTRIBUTION/lib/engines:$VDISTDIR/ext/$DISTRIBUTION/lib:$VDISTDIR/ext/lib:$VDISTDIR/$DISTRIBUTION/jre/lib:system/lib:$VDISTDIR/$DISTRIBUTION/lib"/>
    
  2. Run the command setcap 'cap_net_bind_service=+ep cap_sys_rawio=+ep' INSTALL_DIR/platform/bin/vshell to allow the API Gateway to listen on privileged ports.

API Manager

When API Manager is installed, you must run the update-apimanager script after the API Gateway post-install script to ensure that all paths are up-to-date. For details, see Run update-apimanager.

Update a container deployment

If a fed file is provided as part of building the API Manager container, you must follow these steps to update the fed with the configuration changes:

  1. Install the update on a installation of the API Gateway.

  2. Run the following command:

    /opt/Axway-7.7/apigateway/posix/bin/update-apimanager --fed <path to old file>.fed --oa <path to update file>.fed
    

You do not need to run any API Manager instances.

The fed now contains the updates for the API Manager configuration and can be used to build containers.

Documentation

You can find the latest information and up-to-date user guides at the Axway Documentation portal at https://docs.axway.com.

This section describes documentation enhancements and related documentation.

Documentation enhancements

The latest version of API Gateway, API Manager, and API Portal documentation has been migrated to Markdown format and is available in a public GitHub repository to prepare for future collaboration using an open source model. As part of this migration, the documentation has been restructured to help users navigate the content and find the information they are looking for more easily.

Documentation change history is now stored in GitHub. To see details of changes on any page, click the link in the last modified section at the bottom of the page.

To find all available documents for this product version:

  1. Go to https://docs.axway.com/bundle.
  2. In the left pane Filters list, select your product or product version.

Customers with active support contracts need to log in to access restricted content.

The following reference documents are also available:

  • Supported Platforms - Lists the different operating systems, databases, browsers, and thick client platforms supported by each Axway product.
  • Interoperability Matrix - Provides product version and interoperability information for Axway products.

Support services

The Axway Global Support team provides worldwide 24 x 7 support for customers with active support agreements.

Email mailto:support@axway.com or visit Axway Support at https://support.axway.com.

See Get help with API Gateway for the information that you should be prepared to provide when you contact Axway Support.