Exporting and Importing Assets and Configurations

API Gateway supports the import and export of the assets that you create or configure in API Gateway. You can import archives of APIs, global policies, and other related assets that you have exported and re-create them in API Gateway. This enables you to easily export and archive the assets; and when required, import them to a different instance of API Gateway or redeploy them on the same instance.

Overview

Each artifact in an archive is associated with a universally unique identifier (UUID) that is unique across all API Gateway installations. When importing an archive, the UUID helps in determining whether the corresponding artifact is already available in API Gateway. You can configure whether you want to overwrite the existing artifact or keep the available artifact during the import process.

Note:

Note: Do not attempt to modify and import an archive file because import of modified archive files is not supported.You can export archives from an earlier version to a later version of API Gateway. However, you can not import from a later version to an earlier version. For example, you can not import an 10.5 asset into a 10.3 API Gateway.

You can also export and import assets using the API Gateway REST APIs. For more information, see API Gateway Archive

When you export an asset, the dependent assets are also exported. If any of the exported assets contain secure strings, the user credential information (passwords) associated with the assets is also exported. When you import this exported asset, API Gateway enforces conditions to check the order of import and the dependency evaluation between assets, and the dependent assets along with the user credential data are imported. For example, if you import an API, API Gateway checks and ensures that all associated policies and aliases are imported along with any passwords, if present, before importing the API.

The Overwrite option available for all the assets allows you to decide whether the asset should be imported if an existing version of the asset already exists in the target instance. In scenarios where you select to overwrite the asset in the target instance, API Gateway also checks for any associated passwords and applies the overwrite accordingly. There is no separate overwrite option for the passwords during import. The password uses the overwrite option of the asset it is associated with. For example, if you are importing an alias with a password, the overwrite option provided for the alias is applied for the password as well. If set to true, the password is overwritten if it is already exists in the system.

Functional Privileges

The Export or Import assets and Purge and Archive events category on the Access profile details page has the available import and export privileges. You must assign the following functional privileges for the required permissions:

Accessing the Export and Import commands in the API Gateway user interface

The export command is either a button with the label Export, or the icon icon. You can export multiple items within lists, such as APIs in the API page, by using the export command in the list menu.

You can import assets using the user menu (icon) > Import command.

Assets that can be exported and imported

Path to Page/Tab Assets that can be exported and imported
APIs APIs
Policies > Threat protection Global denial of service
Denial of service by IP
Rules
Mobile device and apps
Alert settings
Policies > Global policies Global policies
Policies > Policy templates Policy templates
Applications Applications
Packages > Packages Packages
Packages > Plans Plans
User menu () > Administration > General
  • Extended settings
  • API fault
  • Approval configuration
  • URL Aliases
  • Custom content-types
  • Callback processor settings
User menu () > Administration > Security
  • Keystore/Truststore
  • SAML issuer
  • Custom assertions
  • Kerberos
  • JWT/OAuth/OpenID
  • Providers
User menu () > Administration > Destinations
  • API Gateway
  • API Portal (only the Event configurations are exported)
  • Elasticsearch (properties on both tabs—Elasticsearch communication and Events—are exported)
  • Email (properties on both tabs—Email configuration and Templates—are exported)
User menu () > Administration > Service registries
  • Service registry
User menu () > Administration > Aliases
  • Aliases

For more information about how to export APIs and global policies, see the following:

Dependencies

Some API Gateway assets use other assets. For example, APIs uses policies, aliases, and other assets. As the configuration of an asset is incomplete without the assets it uses, the export features includes the assets that are used by the asset that you export.

The following table shows the asset dependencies of each type of asset:

Asset Dependencies (Required) Dependencies (Optional)
APIs Policies, Aliases Applications, Application registrations
Applications APIs, Application registrations
Packages APIs, Plans, Policies, Subscriptions
Plans Policies
Subscriptions Packages, Plans Applications
Teams Group
Approval configurations Access profiles
Configuration > Keystore Keystore, Truststore
Email destination Trust store
Service Registry Keystore, Truststore
Custom destinations Keystore, Truststore, Aliases

Importing Asset and Configuration Archives

For information about the import/export process, see Overview.

To import the exported files

  1. Expand the menu options icon icon, in the title bar, and select Import.

  2. Provide the following information:

    Parameter Description
    Select archive file Click Browse to select a file or ZIP format file.
    Overwrite Select an overwrite option:
    • None: If you do not want to overwrite matching objects that exist on the server. Import will fail for the object in the archive if a matching object/asset already exists on the server.
    • All: If you want to overwrite any matching asset that exists on the server. If a match is not found, then a new asset is created.
    • Custom: If you want to select the specific types of assets that will be overwritten on the server if a match is found. If a matching asset exists on the server for an asset type that is not selected in the Custom overwrite list, the import operation will fail.

    Note: If a duplicate asset is found for any asset type that is not selected in the Custom overwrite list, the import will fail
    Note: Some types of assets have dependencies on other asset types. For example, APIs have a dependency on policies, aliases, and applications. Some of the dependencies are required, while others are optional. The required dependencies are always included in the archive when you export the asset. You should consider your requirements and select the assets that need to be overwritten in the Custom list. For more information, see Overview
    API version history Select this option Fix missing versions to fix the API version history.
    On selecting this option, the APi versions are newly linked according to the system version of the APIs.

    Note: API Gateway supports backward compatibility for API Gateway 10.1 version or higher when importing the archives of APIs. If you want to use the archives of API Gateway 10.2 in versions 10.3 and higher, you must export them from API Gateway 10.2 fix 3 or higher.

  3. Click Import.
    The Import report displays the following information:

    Parameter Description
    Type The asset type.
    Successful The number of successful imports for each artifact type.
    Unsuccessful The number of unsuccessful imports for each artifact type.
    Replaced The number of instances replaced for each artifact type.
    Warning The number of warnings displayed during the import of each artifact type. API Gateway displays warning messages when the import is successful but some additional information is required.
  4. Click Download the detail report here > to download the detail report.
    The detail report displays the following information about the imported artifact:

    Parameter Description
    Name The name of the artifact imported.
    Type The artifact type.
    Status The status of the imported artifact. The available values are:
    • Success
    • Replaced
    • Warning
    • Failure
    Explanation The reason if the import fails or if a warning occurs.