Photo by Julia Craice on Unsplash

DevOps personnel can migrate API Products using WSO2 API Controller, adding more value to the CI/CD process in collaboration with WSO2 API Manager. This blog highlights the use cases of migrating API Products and specifies different flag usages using WSO2 API Controller 4.1.0. Let’s begin. 

What is an API Product, and what is covered under WSO2 API Controller 4.1.0.?

An API Product is a packaging mechanism used to bundle a preferred set of resources from multiple APIs and expose it as a separate API interface, which in turn, can be consumed by subscribers. For more information on API Products, refer to the official documentation here. WSO2 API Controller 4.1.0 has six functionalities related to API Products:

1. Import an API Product
2. Export an API Product
3. List API Products
4. List API Product revisions
5. Delete an API Product
6. Generate keys (tokens) for an API Product

We will highlight exporting and importing API Products using WSO2 API Controller 4.1.0 by showing user scenarios that can be raised when migrating API Products across environments.

Prerequisites

Assuming you already installed Oracle Java SE Development Kit (JDK) version 11.\* or 1.8.\* and set the  JAVA_HOME  environment variable (for more information on adding this for different operating systems, click here) you must also satisfy these requirements:

• Download the latest version of WSO2 API Manager
• Download and initialize WSO2 API Controller 4.1.0 (apictl 4.1.x)

What is Migration?

In the context of WSO2 API Controller, migration refers to exporting an API, API Product or Application from one environment and importing it to another. The main advantage of the migration process is that all related artifacts such as documentation, mediation policies, certificates, thumbnail etc. of APIs/API Products and keys, subscriptions, etc. of Applications will be moved alongside the corresponding API, API Product, or Application. 

Exporting an API Product

There are two use cases when it comes to exporting an API Product. 

1. Export the Current Copy of an API Product.

Assume you have an API Product, “TestAPIProduct” in the development environment as shown in Figure 1, which was created using the resources “PizzaShackAPI-1.0.0” and “SwaggerPetstore-1.0.5”.

Figure 1: “TestAPIProduct” in the development environment

You can export the Current Copy (the current state of the API Product) using the following command. 

The above -n (--name) and -e (--environment) flags are mandatory. There is an optional flag introduced from WSO2 API Controller 4.1.0 onwards, known as the --preserve-status. As implied, it maintains the API Product status during the export process to prevent it from being exported in the CREATED status. 

Note: The Current Copy will not have deployment related information inside the exported zip file. Hence, re-importing this to another environment will not create and deploy API Product revisions in that environment. To do this, you must follow the next section, Export an API Product with deployments.

If we inspect the exported API Product archive, it will have the following folder structure.

TestAPIProduct-1.0.0
├── api_product_meta.yaml
├── api_product.yaml
├── APIs
│ ├── PizzaShackAPI-1.0.0
│ │├── api.yaml
│ │└── Definitions
│ │ └── swagger.yaml
│ └── SwaggerPetstore-1.0.6
│ ├── api.yaml
│ └── Definitions
│ └── swagger.yaml
└── Definitions
└── swagger.yaml

You can see the dependent APIs (current copies of the given APIs without deployments) have been exported as well. 

2. Export an API Product with deployments

You can export an API Product along with its deployments (in other words, you are exporting an API Product revision) using either of the following commands. 

Note: The --latest flag will export the --latest revision of the API Product and --rev flag will export the API Product revision specified by the number (In the above example, it will export revision number 1)

If we inspect the exported API Product archive, the folder structure is as follows: 

TestAPIProduct-1.0.0/
├── api_product_meta.yaml
├── api_product.yaml
├── APIs
│ ├── PizzaShackAPI-1.0.0
│ │├── api.yaml
│ │└── Definitions
│ │ └── swagger.yaml
│ └── SwaggerPetstore-1.0.6
│ ├── api.yaml
│ └── Definitions
│ └── swagger.yaml
├── Definitions
│ └── swagger.yaml
└── deployment_environments.yaml

When compared to the earlier folder structure, you may observe the existence of the deployment_environments.yaml file. This contains the list of deployed gateways (deployment details) of the particular API Product.

Furthermore, there is no way to export the deployment details of the dependent APIs along with the exported API Product. If you want to export the API’s deployment details, you must export APIs individually by providing the --latest or --rev flags.

Importing an API Product

Importing an API Product can be done in several ways to match your requirement. Let’s review nine use cases where you may use different optional flag combinations as needed. Here, there are three optional flags that you can test. Those are:

1. --import-apis
2. --update-api-product
3. --update-apis

The behavior of the above three flags can be summarized as below.

Let’s move on to the nine use cases where you can use the three flags mentioned earlier.

1. Importing a new API Product with a new set of dependent APIs

Here, we assume the API Product or dependent APIs are not in the environment you are trying to import to. Hence, you must import the APIs by specifying the --import-apis flag along with the API Product.

Note:- A user role with both apim:api_product_import_export and apim:api_import_export permissions can perform this operation (Please see here for more information.)

2. Importing a fresh API Product when dependent APIs are already imported to WSO2 API Manager successfully

Here, it is assumed the dependent APIs are already imported to the environment. So, no optional flags need to be specified. 

Note:- A user role with apim:api_product_import_export permission can perform this operation (Please see here for more information). 

3. Importing a fresh API Product when dependent APIs are already imported to WSO2 API Manager successfully and you want to update the APIs

Assuming the dependent APIs are already imported, you must also specify the flag --update-apis.

Note:- A user role with both apim:api_product_import_export and apim:api_import_export permissions can perform this operation (Please see here for more information). 

4. Update the API Product by changing the meta information and adding/removing the resources of the API Product

Here, we assume the API Product and dependent APIs are already imported. Since you must update the API Product, you must specify the flag --update-api-product.

Note:- A user role with apim:api_product_import_export permission can perform this operation (Please see here for more information). 

5. Update the API Product by adding new resources to both the API Product and the API(s)

We assume both the API Product and the dependent APIs are already imported. Since you need to update the API Product and the dependent APIs, you must specify the flag --update-apis.

Note:- A user role with both apim:api_product_import_export and apim:api_import_export permissions can perform this operation (Please see here for more information). 

6. Update only the dependent APIs.

Here, we assume the API Product and the dependent APIs are already imported. Since you need to update the dependent APIs, you need to specify the flag --update-apis.

Note:- A user role with both apim:api_product_import_export and apim:api_import_export permissions can perform this operation (Please see here for more information).

7. Import a fresh API Product and its dependent APIs to another tenant (with --preserve-provider=false).

Here, we assume the API Product or dependent APIs are not already in the tenant that you are trying to import to. So, you must ask to import the APIs by specifying the --import-apis flag, along with the API Product.

Note:- A user role with both apim:api_product_import_export and apim:api_import_export permissions can perform this operation (Please see here for more information). 

8. Update an already imported API Product but not its dependent APIs in another tenant (with — preserve-provider=false).

Here, we assume the API Product and dependent APIs are already imported to the tenant. Since you need to update the API Product, you need to specify the flag --update-api-product.

Note:- A user role with apim:api_product_import_export permission can perform this operation (Please see here for more information). 

9. Update an imported API Product and its dependent APIs in another tenant (with — preserve-provider=false).

Here, we assume the API Product and dependent APIs are already imported. Since you must update the API Product and the dependent APIs, you must specify the flag --update-apis.

Note:- A user role with both apim:api_product_import_export and apim:api_import_export permissions can perform this operation (Please see here for more information).

Concluding Thoughts

There are several other use cases that have not been discussed here, but can be addressed when the above scenarios have been understood. To find out more about WSO2 API Controller 4.1.0, please visit its commands catalog here.