A Gift to DevOps to Migrate API Products

Happy New Year to you and your loved ones!

This is the first time that we are meeting in 2021. I am going to give you a gift for the new year! Are you ready, folks?

For DevOps, this is a gift which they have been counting fingers eagerly. It is the “Support for Migrating API Products using WSO2 API Controller”. Of course, if you are a fan of WSO2 API Manager and WSO2 API Controller, you may already know that in the previous API Controller releases, the operations related to APIs and Applications were available. The new release, WSO2 API Controller 3.2.0 incorporates the operations related to API Products thus adding more value to the assistance from the API Controller to the CI/CD process.

Yeah, you can refer to the official documentation here to know about this. But this article will especially highlight the use cases of migrating API Products while also specifying the different flag usages to ease DevOps burden. If you do not understand what I said, don’t worry. Just go through the article and you may receive your gift eventually.

Let me start with a basic question.

What is an API Product and what will be covered under WSO2 API Controller 3.2.0?

An API Product is a packaging mechanism that you can use when you need to bundle a preferred set of resources from multiple APIs and expose it as a separate API interface, which can be consumed by subscribers.

For more information on API Products, please refer here (the official documentation). WSO2 API Controller 3.2.0 introduces five (5) new functionalities related to API Products, but this article will discuss only Exporting and Importing API Products using the API Controller by highlighting the user scenarios that can be raised when migrating API Products from one environment to another.

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

This is the new year gift that I am going to offer you guys. Let’s see whether you will like it.

First Things First

I am going to be a bit techy now. Please refer to the following prerequisites if you want to have hands-on experience with what I am going to say. Otherwise, you are free to ignore this.

Under the assumption that you have already installed Oracle Java SE Development Kit (JDK) version 11.\* or 1.8.\* and set the JAVA_HOME environment variable (For more information on setting the JAVA_HOME environment variable for different operating systems, see Setup and Install.) you need to satisfy the below requirements.

What is “Migration”?

In the context of the WSO2 API Controller, “Migration” stands for exporting an API/API Product/Application from one environment and importing it to another environment. Make sure to remember the main advantage of the migration process is that the related artifacts such as documentation, mediation policies, certificates, thumbnail etc. of APIs/API Products and keys, subscriptions, etc. of Applications will be exported/imported along with the corresponding API/API Product/Application.

I will be dividing this article into two (2) halves where the first half will discuss the use cases of “Exporting an API Product”, while the second half will discuss the use cases of “Importing an API Product”. The latter half has several important use cases where a DevOps can use the flags in APICTL (API Controller) API Product related commands to manipulate the process as he/she wants.

Exporting an API Product

There is only one use case when it comes to exporting an API Product and it is pretty straightforward. I will use an example to explain it to you briefly.

Assume that I have an API Product named “TestAPIProduct” in the production environment as below, which was created using the resources of “PizzaShackAPI-1.0.0” and “SwaggerPetstore-1.0.5”.

“TestAPIProduct” in the production environment

You can export this API Product using the command below.

apictl export api-product -n TestAPIProduct -e production

The above -n (- -name) and -e (- -environment) flags are mandatory. Optionally you can provide -r (- -provider) and -f (- -format) flags as well. (For more information type “apictl export api-product — help”)

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

TestAPIProduct-1.0.0
├── api_product_params.yaml
├── APIs
│ ├── PizzaShackAPI-1.0.0
│ │ └── Meta-information
│ │ ├── api.yaml
│ │ └── swagger.yaml
│ └── SwaggerPetstore-1.0.5
│ └── Meta-information
│ ├── api.yaml
│ └── swagger.yaml
└── Meta-information
├── api.yaml
└── swagger.yaml

You can see that the dependent APIs have been exported as well. If anyone wants to provide params files for APIs (api_params.yaml), you just need to add those to the relevant API folders as shown below.

└── TestAPIProduct-1.0.0
├── api_product_params.yaml
├── APIs
│ ├── PizzaShackAPI-1.0.0
│ │ ├── api_params.yaml
│ │ └── Meta-information
│ │ ├── api.yaml
│ │ └── swagger.yaml
│ └── SwaggerPetstore-1.0.5
│ ├── api_params.yaml
│ └── Meta-information
│ ├── api.yaml
│ └── swagger.yaml
└── Meta-information
├── api.yaml
└── swagger.yaml

When importing the API Product, the params files inside the API directories will also be processed and considered.

Importing an API Product

This is the most important place where the DevOps may have a dream to receive a gift. Don’t worry the gift is ready!

Note:- Sometimes you may think this is a bit more technical. Of course, this can be because I will be targetting YOU — DevOps!

Importing an API Product can be done in several ways to match with your requirement. I will be discussing nine (9) use cases where you can use different optional flag combinations to match with your needs. Here, there are three (3) optional flags that you can play with which are,

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

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

if --import-apis is specified 
then Import the API Product and its dependent APIs
else if --update-apis is specified
then Update the dependent APIs AND the respective API Product
else if --update-api-products is specified
then Only update the respective API Product
else
Only import the API Product

Let’s move on to the nine (9) use cases where you can use the above three (3) flags in different ways to expand the above summary further.

1. Import a fresh API Product with a fresh set of dependent APIs.

This is the basic use case. Here, it is assumed that the API Product or the dependent APIs are not in the environment that you are trying to import. So you should ask to import the APIs (by specifying the — import-apis flag) along with the API Product.

Note:- Only a user role who has both apim:api_product_import_export and apim:api_import_export scope can do this operation. (Example: Internal/devops)

Required Optional Flags:
--import-apis
Example:
apictl import api-product -f /home/wasura/.wso2apictl/exported/api-products/production/TestAPIProduct_1.0.0.zip -e production --import-apis

2. Import a fresh API Product when dependent APIs are already imported to the API Manager environment successfully.

Here, it is assumed that the dependent APIs are already imported to the environment. So you do not need to specify any optional flag to do this task.

Note:- A user role who has apim:api_product_import_export scope can do this operation. (Example: Internal/devops)

Example:
apictl import api-product -f /home/wasura/.wso2apictl/exported/api-products/production/TestAPIProduct_1.0.0.zip -e production

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

Here, it is assumed that the dependent APIs are already imported to the environment. Also, since you need to update those APIs, you need to specify the flag — update-apis.

Note:- Only a user role who has both apim:api_product_import_export and apim:api_import_export scope can do this operation. (Example: Internal/devops)

Required Optional Flags:
--update-apis
Example:
apictl import api-product -f /home/wasura/.wso2apictl/exported/api-products/production/TestAPIProduct_1.0.0.zip -e production --update-apis

Furthermore note that, in this scenario, if you specify — import-apis and/or — update-api-product flags, no harm will be done. But make sure to specify the — update-apis flag for sure.

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

Here, it is assumed that the API Product and the dependent APIs are already imported tothe environment. Also, since you need to update the API Product, you need to specify the flag — update-api-product.

Note:- A user role who has apim:api_product_import_export scope can do this operation. (Example: Internal/devops)

Required Optional Flags:
--update-api-product
Example:
apictl import api-product -f /home/wasura/.wso2apictl/exported/api-products/production/TestAPIProduct_1.0.0.zip -e production --update-api-product

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

Here, it is assumed that the API Product and the dependent APIs are already imported to the environment. Also, since you need to update the API Product and the dependent APIs, you need to specify the flag — update-apis.

Note:- Only a user role who has both apim:api_product_import_export and apim:api_import_export scope can do this operation. (Example: Internal/devops)

Required Optional Flags:
--update-apis
Example:
apictl import api-product -f /home/wasura/.wso2apictl/exported/api-products/production/TestAPIProduct_1.0.0.zip -e production --update-apis

Furthermore note that, in this scenario, if you specify — update-api-product flag, no harm will be done. But make sure to specify the — update-apis flag.

6. Update only the dependent APIs.

Here, it is assumed that the API Product and the dependent APIs are already imported to the environment. Also, since you need to update the dependent APIs, you need to specify the flag — update-apis.

Note:- Only a user role who has both apim:api_product_import_export and apim:api_import_export scope can do this operation. (Example: Internal/devops)

Required Optional Flags:
--update-apis
Example:
apictl import api-product -f /home/wasura/.wso2apictl/exported/api-products/production/TestAPIProduct_1.0.0.zip -e production --update-apis

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

Here, it is assumed that the API Product or the dependent APIs are not in the tenant that you are trying to import. So you should ask to import the APIs (by specifying the — import-apis flag) along with the API Product.

Note:- Only a user role who has both apim:api_product_import_export and apim:api_import_export scope can do this operation. (Example: Internal/devops)

Required Optional Flags:
--import-apis
Example:
apictl import api-product -f /home/wasura/.wso2apictl/exported/api-products/production/TestAPIProduct_1.0.0.zip -e production --import-apis --preserve-provider=false

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

Here, it is assumed that the API Product and the dependent APIs are already imported to the tenant. Also, since you need to update the API Product, you need to specify the flag — update-api-product.

Note:- A user role who has apim:api_product_import_export scope can do this operation. (Example: Internal/devops)

Required Optional Flags:
--update-api-product
Example:
apictl import api-product -f /home/wasura/.wso2apictl/exported/api-products/production/TestAPIProduct_1.0.0.zip -e production --update-api-product --preserve-provider=false

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

Here, it is assumed that the API Product and the dependent APIs are already imported to the environment. Also, since you need to update the API Product and the dependent APIs, you need to specify the flag — update-apis.

Note:- Only a user role who has both apim:api_product_import_export and apim:api_import_export scope can do this operation. (Example: Internal/devops)

Required Optional Flags:
--update-apis
Example:
apictl import api-product -f /home/wasura/.wso2apictl/exported/api-products/production/TestAPIProduct_1.0.0.zip -e production --update-apis --preserve-provider=false

Furthermore note that, in this scenario, if you specify — update-api-product flag, no harm will be done. But make sure to specify the — update-apis flag.

Last but not Least

This article explained to you “How to use different flag combinations to import/export API Products using the WSO2 API Controller?”. If you are a DevOps who is looking forward to using API Controller, this can be the perfect New Year gift for you.

There can be several other use cases that I have not discussed here, but those scenarios can be addressed when the above basic nine (9) scenarios have been understood.

Hope you like my gift and stay tuned to receive more gifts with future API Controller releases.

Thanks and Goodbye! Stay safe everyone…

References

--

--

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store