+1.972.608.4777

AVIO Consulting

API Migration in API Manager 2.x

Jun 26, 2018 | MuleSoft

Overview

API Manager 2.x has support for environments which correspond to those defined within Anypoint Platform for the Runtime Manager (i.e. DEV, QA, PROD). This is an improvement over the 1.x version, which typically required the construction of version names to reflect an environment. With this enhanced functionality comes a bit of complexity during API deployment. Within the article, we will dive into the complexity as well as provide some deployment tips.

Background

Within API Manager 2.x, the migration lifecycle of an API starts with the RAML defined within Design Center, published to Exchange, then imported from Exchange to be managed within the API Manager. Once an API is imported into API Manager, policies can be applied, tiers defined, alerts added.

{{cta(’21d05245-861a-4547-b6c1-8d565352ba15′,’justifycenter’)}}

The Glue: Auto-Discovery

An API that is imported from Exchange can be paired with a deployed application, making the API ‘Active’ (managed). This pairing is done by specifying the following within a Mule application:

 <api-platform-gw:api apiName="${api.name}" version="${api.version}" flowRef="my-api-main" create="true"  doc_name="API Autodiscovery"/>

The pairing by the apiName and version that correlate to the API Name and API Version specified in the API Manager for the given API:

API Exchange

You might notice that the values defined for the application name and version used within autodiscovery are a little bit different between API Manager 2.x vs. 1.x.  The new naming convention is:

  • API Version: Version + instance id
  • API Name: “groupId:” + Anypoint Platform group Id + “assetId:” + RAML name

After an API has been deployed, if the pairing was done correctly, the API will now be set to ‘Active’ status within the API Manager:

API Manager

API Migration: Cloudhub Applications

Since the API version now contains the instance identifier, which is different in each environment, how do we go about deploying our APIs to these environments? Do we need to do it manually? Do we need to hardcode the auto-discovery properties? Do we need to apply policies in each environment? The good news is that for Cloudhub applications, the answer to all these questions is ‘no’ (see next section for on-premise applications).

Within API Manager, an API can be promoted from one environment to another. This allows all policies, tiers, and alerts that are defined for a given environment to be promoted up the environments. Any policies applied in lower environments will persist as they move up the environments.

With the usage of the MuleSoft APIs available within Anypoint Platform (https://anypoint.mulesoft.com/apiplatform/anypoint-platform/#/portals) this process can be automated, utilized from within your CI/CD pipelines during deployment, for example.

These APIs will allow you to query for a list of existing APIs for a given environment, promote from one environment to the next, along with retrieving the API version and name for auto-discovery:

  • Authenticate and retrieve access token (POST https://anypoint.mulesoft.com/accounts/login)
  • Query for environment identifier (GET “https://anypoint.mulesoft.com/apiplatform/repository/v2/organizations/orgId/environments). Environment identifiers are used in the next API calls.
  • Retrieve APIs for given environment, including API version and API Name (GET “https://anypoint.mulesoft.com/apimanager/api/v1/organizations/” + orgId + “/environments/” + envId + “/apis”)
  • If API does not exist in specified environment, promote it from the lower environment, i.e. DEV to QA (POST https://anypoint.mulesoft.com/apimanager/api/v1/organizations/ + groupId + ”/environments/” + toEnvId + “/apis”). POST body:
{"instanceLabel": "label",

"promote": {

     "originApiId": lower environment API identifier,

     "policies": { "allEntities": true },

     "tiers": { "allEntities": true },

     "alerts": {"allEntities":true }

}

} 

Once you retrieve the API Version and API Name, pass these values into your deployment script, as demonstrated in the next section.

Auto-Discovery Properties

In conjunction with Maven, the auto-discovery properties can be populated during deployment. Within the POM, provide placeholders for the API Name and API Version as shown below:

  <plugin>

               <groupId>org.mule.tools.maven</groupId>

               <artifactId>mule-maven-plugin</artifactId>

               <version>2.2.1</version>

               <configuration>

                 <workerType>Micro</workerType>

                 <workers>1</workers>

                 <deploymentType>cloudhub</deploymentType>

                 <muleVersion>${mule.version}</muleVersion>

                 <username>${env.deploy.username}</username>

                 <password>${env.deploy.password}</password>

                 <redeploy>true</redeploy>

                 <environment>${ch.env.name}</environment>

                  <properties>

                      <api.name>${api.name}</api.name> <!-- Must correspond with name of API defined within API Manager, used in autodiscovery -->

                      <api.version>${api.version}</api.version> <!-- Must correspond with the version of the API defined within API Manager, used in autodiscovery -->

                      <env>${env}</env> <!-- dev, qa, or prod. Used to identify which properties file used at runtime -->

                      <anypoint.platform.client_id>${anypoint.platform.client_id}</anypoint.platform.client_id>

                      <anypoint.platform.client_secret>${anypoint.platform.client_secret}</anypoint.platform.client_secret>

                  </properties>

               </configuration>

               <executions>

                 <execution>

                   <id>deploy-cloudhub</id>

                   <phase>deploy</phase>

                   <goals>

                     <goal>deploy</goal>

                   </goals>

                 </execution>

               </executions>

            </plugin>

Now using the MuleSoft APIs, retrieve the API Name and API Version from Anypoint Platform, plugging in the values at deployment. For example:

mvn clean package mule:deploy -Dapi.name=name -Dapi.version=version other params….

{{cta(‘ce02041b-c47a-4822-ba1b-c55b2e73bc3d’,’justifycenter’)}}

API Migration: On-Premise Applications

Due to a limitation with deployment parameters, on-premise deployments cannot be configured to dynamically specify the auto-discovery parameters. Given this, the APIs will be manually promoted from the API Manager Dev environment to QA, Prod, etc. In API Manager:

API Manager Dev

Select the environment and API to promote:

Promote API

{{cta(‘b8ba5abd-1f2d-4416-bf68-91f04e543129′,’justifycenter’)}}