Upgrade CA Live API Creator

Upgrade CA Live API Creator
calac41
This article explains how to upgrade from a previous version of 
CA Live API Creator
. It also explains how to roll back the upgrade if you experience unresolved issues during the upgrade process.
The upgrade process that you use is based on the type of database management system (DBMS) you are using as your admin database. Apache Derby admin databases are not upgraded automatically.
 The single-user version demonstration package of 
CA Live API Creator
 that is based on Jetty (demonstration package) uses the Derby DBMS as the admin database. If you have installed this version of 
CA Live API Creator
, you must complete the steps in the "Upgrade If You Have Configured Derby as Your Admin Database" section.
For more information about the changes to field names in rules and data sources that occur when you upgrade from a previous version of 
CA Live API Creator
, see Release Notes.
The upgrade process saves your APIs, including the metadata–database schema, business rules, resource endpoints, security definitions for users, and roles–for those APIs, to the newer version of 
CA Live API Creator
.
In this article:
 
 
3
 
 
Upgrade 
CA Live API Creator
 
Use the following process to upgrade from a previous version of 
CA Live API Creator
:
  1. Upgrade 
    CA Live API Creator
     based on the type of database management system (DBMS) you are using as your admin database:
Back up Your Admin Database
Before upgrading 
CA Live API Creator
, back up of your admin database and the web application ARchive (WAR) file for the previous version of 
CA Live API Creator
. Make sure that you have access to this backup. If you experience unresolved issues during the upgrade, you can roll back the upgrade using this backup.
For more information about how to roll back the upgrade, see the "Roll Back During Upgrade" section.
Back up your APIs and databases.
Upgrade If You Have Configured a Database Other Than Derby as Your Admin Database
If you have a previous version of 
CA Live API Creator
 installed and you are using a DBMS other than Derby as your admin database, installing the WAR file for the newer version of 
CA Live API Creator
 and starting your container the first time automatically upgrades your admin database.
Verify the Prerequisites
Before you begin the upgrade process, verify the following prerequisites:
  • You have imported the API Server license.
    For more information about how to obtain a license, contact CA Technologies support.
     
    CA Live API Creator
     runs in read-only mode until you have installed a valid license.
    For more information about how to install the API Server license, see Import the API Server License.
  • You have cleared your browser cache.
Verify That You Do Not Have Incomplete Rules
If you are using the MySQL or PostgreSQL as your admin database, verify that you do not have incomplete rules.
 
Follow these steps:
 
  1. Log in to your current version of API Creator as a system administrator user (
    sa
    ).
    If the dialog about installing a license appears, dismiss the dialog.
  2. Open the CA Live API Creator Admin project API (Admin API).
  3. In the Execute section, click 
    REST Lab
    .
    The Request page opens by default.
  4. From the 
    Auth Token
     drop-down, select the bottom-most authentication token.
  5. Enter the URL based on your 
    CA Live API Creator
     installation, and then click 
    GET
    :
    http://localhost:8080/rest/abl/admin/v2/admin:rules?sysfilter=equal(attribute_name: null)&sysfilter=equal_or(ruletype_ident:1,ruletype_ident:2,ruletype_ident:3,ruletype_ident:4,ruletype_ident:11,ruletype_ident:12)
  6. If the response in the Response pane is empty (empty brackets display), then your rules are complete, and you can proceed with the upgrade steps. If the response includes rule objects, then you must fix these rules. You can fix these rules by deleting them or by editing them and specifying a column to hold the result of the rule.
  7. Repeat steps 5 and 6 until the query returns an empty result.
Verify That Your API Does Not Have Duplicate Library Short Names
Each library in your API must include a unique short name.
 
Follow these steps:
 
  1. Log in to your current version of API Creator as an API developer user (usually, the 
    admin
     user).
  2. Open any API.
  3. In the Create section, click 
    API Properties
    .
    The Details tab appears by default.
  4. Click the 
    Libraries
     tab.
    The Your Libraries page appears by default.
  5. For each library, complete the following:
    1. Click 
      Change
      .
      The Logic library dialog opens.
    2. Make a note of the 
      Short name
       value, and then click 
      Cancel
      .
  6. If your API includes libraries that have duplicate short names, change the short name so that each is unique.
Upgrade To a Newer Version of 
CA Live API Creator
 
You can upgrade to a newer version of 
CA Live API Creator
 that is installed on the following Java containers:
 
Upgrade to a Newer Version Installed on Apache Tomcat
Use the following procedure if you have installed 
CA Live API Creator
 on Tomcat and you are using a DBMS other than Derby as your admin database.
  1. Stop the Tomcat service by issuing the following command:
    (Mac/Unix)
    sh shutdown.sh
    (Windows)
    shutdown
  2. Create a copy of the 
    ROOT.war
     file to recall the version number.
  3. In the 
    %Tomcat_Home%/webapps
     directory, delete the 
    ROOT.war
     file and the 
    ROOT
     folder.
  4. Rename the 
    /development/CALiveAPICreator.war
     file to 
    ROOT.war
    .
  5. Copy the 
    ROOT.war
     file into the 
    %Tomcat_Home%/webapps
     directory.
  6. Start the Tomcat service by issuing the following command:
    (Mac/Unix)
    sh startup.sh
    (Windows)
    startup
You have upgraded 
CA Live API Creator
 on Tomcat. 
CA Live API Creator
 is at the root URL.
 
Upgrade to a Newer Version Installed on Oracle WebLogic
Use the following procedure if you have installed 
CA Live API Creator
 on WebLogic and you are using a DBMS other than Derby as your admin database.
  1. Retrieve the latest 
    CA Live API Creator
     WAR file from your 
    CA Live API Creator
     installation bundle.
  2. Using the WebLogic admin web console, install the 
    CALiveAPICreator<version>.WAR
     file.
    For more information about how to install or upgrade WAR files using the administrative console, see the Oracle WebLogic documentation.
You have upgraded 
CA Live API Creator
 on WebLogic.
 
Upgrade to a Newer Version Installed on IBM WebSphere
Use the following procedure if you have installed 
CA Live API Creator
 on WebSphere and you are using a DBMS other than Derby as your admin database.
  1. Retrieve the latest 
    CA Live API Creator
     WAR file from your 
    CA Live API Creator
     installation bundle.
  2. Using the administrative console, install the 
    CALiveAPICreator<version>.WAR
     file as an application in your WebSphere server.
    For more information about how to install application files on WebSphere application server, see the IBM WebSphere documentation.
You have upgraded 
CA Live API Creator
 on WebSphere.
 
Upgrade to a Newer Version Installed on JBoss
Use the following procedure if you have installed 
CA Live API Creator
 on JBoss and you are using a DBMS other than Derby as your admin database.
  1. Retrieve the latest 
    CA Live API Creator
     WAR file from your 
    CA Live API Creator
     installation bundle.
  2. Install the 
    CALiveAPICreator<version>.WAR
     file.
    For more information about how to install WAR files in your JBoss Server, see the JBoss documentation.
You have upgraded 
CA Live API Creator
 on JBoss.
Upgrade If You Have Configured Derby as Your Admin Database
If you are using this DBMS as your admin database, you must upgrade from a previous version of 
CA Live API Creator
 using this upgrade process.
 
CA Live API Creator
 support
 
Derby as an admin database only for demonstration and proof of concept (POC) purposes. Using Derby as your admin database limits your ability to upgrade to the next 
CA Live API Creator
 release.
Verify the Prerequisites
Before you begin the upgrade process, ensure that you have completed the following prerequisites:
  • You have cleared your browser cache.
  • (Tomcat and Amazon Web Services (ASW) Elastic Beanstalk) You have installed the newer version of 
    CA Live API Creator
     in a separate directory and you are using a new admin database name.
     Do not copy a previous download of the admin database to the directory for the newer version of the admin database.
  • You have ensured the newer version of API Server is up and running.
    Ensure that you have accepted the End User License Agreement (EULA).
    For more information about the API Server license and how to upload the license file, see Import the API Server License.
  • For each of your existing APIs, you have completed the following steps:
    1. You have cleared the 
      Used
       checkbox for each JavaScript library your API is referencing, and then saved your changes.
      For more information about this checkbox, see Logic Libraries.
    2. You have exported the API.
      For more information about how to export an API, see Import and Export APIs.
  • You have copied the Java JAR files that you use to the 
    lib
     directory for the newer version of 
    CA Live API Creator
    .
Install the Newer Version of 
CA Live API Creator
 
For more information about how to install 
CA Live API Creator
, see Installing and Upgrading.
Install the 
CA Live API Creator
 Admin Command-Line Interface
For more information about how to install the 
CA Live API Creator
 Admin command-line interface (Admin CLI), see Install NodeJS and Command Line Utilities.
Export the Content in the Current Repository
Export the APIs that are in your current version of 
CA Live API Creator
, including the LIBRARY, PROJECT, GATEWAY, and AUTHPROVIDER repository objects.
For more information about how to export APIs, see Import and Export APIs.
 
Follow these steps:
 
  1. Log in to the current API Server as an administrator user using the Admin CLI by issuing the following commands:
    $lacadmin login -u <admin user name> -p <the password for your TeamSpace user> <URL for the API Server> -a <alias for the API Server>
    $lacadmin use <alias>
    For example:
    $lacadmin login -u admin -p Password1 http://localhost:8080 -a MyAPIServer
    $lacadmin use <alias>
    An export manifest of your current repository objects and an empty 
    --directory <directory name>
     directory are created.
  2. (Optional) Export your custom authentication providers by issuing the following commands:
    $lacadmin authprovider list
    $lacadmin authprovider export --ident <ident> --file authprovider.json
  3. (Optional) Export the API Gateways in your TeamSpace by issuing the following command:
    $lacadmin gateway export --file <directory name>/GATEWAYS.json
  4. Export the APIs that are contained within your TeamSpace, including your data source password in the API export file in encrypted form. The following code block shows an example of scripting the export of the APIs that are contained within a TeamSpace to the 
    allmyapis.zip
     file:
    $lacadmin teamspace exportRepos --file allmyapis.zip --format zip --passwordstyle encrypted
    For more information about how to export the APIs contained within a TeamSpace, see GitHub.
The API export files include the JavaScript libraries that the API uses.
 
CA Live API Creator
 exports the authentication providers, API Gateway definitions, APIs, and JavaScript libraries that it finds are exported.
Import your JSON Files to the Newer Version of 
CA Live API Creator
 
Import your authentication providers and APIs into the newer version of 
CA Live API Creator
.
You can import this content to the newer version of API Server using one of the following methods:
  • Using the Admin CLI.
  • Using import commands to import the API and the JavaScript user libraries.
     If you use this method, you must import your authentication providers and API Gateway definitions using API Creator.
This procedure explains how to import to the newer version of API Server using the Admin CLI.
 
Follow these steps:
 
  1.  Connect to the newer version of API Server by issuing the following commands:
    $lacadmin login -u <admin user name> -p <the admin password for your account> http://localhost:8080 -a <alias for the newer version of API Server>
    $lacadmin use <alias for the newer version of API Server>
  2. (Optional) For each authentication provider, import your authentication provider by issuing the following command:
    $lacadmin authprovider import --file <directory name>/AUTHPROVIDER_{each authentication provider}.json
  3. Import the APIs that are part of the TeamSpace by issuing the following command, for example:
    $lacadmin api import --file allmyapis.zip --namecollision replace_existing
     Before you can use your imported API, enter your password for each data source in API Creator. You can also update the password for each data source using the Admin CLI.
    For more information about how to modify passwords, see Database Connectivity.
     
  4. (Optional) Import your API Gateway definitions by issuing the following command:
    $lacadmin gateway import --file <directory name>/GATEWAYS.json
Your JavaScript user libraries, resources, authentication providers, API Gateway definitions, and APIs are imported to the newer version of API Server.
Set the Role-Level Permissions to Functions
Follow these steps:
  1. Set the visibility to the function REST endpoints. Set the role-level permissions to the functions.
  2. Set the default role-level access to functions. For each of the roles that you have defined in your API, if the role requires execute function priveleges, select the 
    Execute
     checkbox.
For more information about how to set role-level permissions to functions, see Role-Based Endpoint Access.
Upgrade If You Have Configured to Run as a Cluster 
Use the following process: 
  1. Stop all nodes in the cluster.
  2. On one of the nodes, complete the following steps:
    1. Install the WAR file for the newer version of 
      CA Live API Creator
      .
    2. Restart the node.
    3. Verify that the newer version of 
      CA Live API Creator
       is running.
  3. Repeat step 2a and 2b for the remaining nodes in the cluster. 
You have upgraded 
CA Live API Creator
 that is running as a cluster.
Roll Back During Upgrade
In the event that you encounter unresolved issues during the upgrade process, you can roll back your upgrade.
 
Prerequisites:
 
  • You have the WAR file of the previous version of 
    CA Live API Creator
    , either taken as a backup or from the 
    CA Live API Creator
     installation bundle of the previous version of 
    CA Live API Creator
    .
  • You have cleared your browser cache.
Roll Back If You Have Configured to Run on a Single Node
Use the following process:
  1. Stop 
    CA Live API Creator
     on the server where it is installed.
  2. Restore the admin database to the version of the backup that you created prior to upgrading 
    CA Live API Creator
    .
  3. Install 
    CA Live API Creator
     using the backup copy of the WAR file for the previous version of 
    CA Live API Creator
    .
  4. Start 
    CA Live API Creator
     on the server.
  5. Verify that you can do the following:
    • Log in and connect to the previous version of 
      CA Live API Creator
    • Test an API endpoint from the REST Lab.
You have rolled back the upgrade of  
CA Live API Creator
 running on a single node.
Roll Back If You Have Configured to Run as a Cluster (Multiple Nodes)
Use the following process:
  1. Stop 
    CA Live API Creator
     on all nodes in the cluster where it is installed. 
  2. Restore the admin database to the version of the backup that you created prior to upgrading 
    CA Live API Creator
    .
  3. On one of the nodes, complete the following steps:
    1. Install 
      CA Live API Creator
       using the backup copy of the WAR file for the previous version of 
      CA Live API Creator
      .
    2. Start 
      CA Live API Creator
      .
  4. Verify that you can do the following:
    • Log in and connect to the previous version of 
      CA Live API Creator
    • Test an API endpoint from REST Lab.
  5. Repeat step 3 for the remaining nodes in the cluster.
  6. Verify in your logs that all incoming requests are routed to the cluster of nodes.
You have rolled back the upgrade of  
CA Live API Creator
 running as a cluster.