Introduction

When you need to take down a service for maintenance, you need confidence in knowing that the rest of your APIs and client applications will continue to run smoothly. How can you be sure when you know the user list for the service documentation is unreliable and you don’t always know which APIs or applications depend on that service?

Now, you can use the API Connect Impact Analysis tool to help you understand these dependencies between your services and the APIs and client applications that rely on them. This tutorial shows how you can download and use this tool to help assess your API organizations.

Tool overview

The API Connect Impact Analysis tool is a Node.js application. To use it, you run a series of commands on an API Connect command line in the interactive interface. The tool then seamlessly evaluates your API catalog, and returns any dependencies between the APIs, applications, products, plans, or back-end services that you might have. The results help you to visualize and understand the critical dependencies between all APIs and their dependent services, as shown in the following example. This example is a snippet of the complete results that we show later after running the tool.

├────>  Service Host -  https://httpbin.org
│    └────>  Service ContextRoute - /ip
│         ├────>  API - Demo1 : 1.0.0
│         └────>  API - testing : 1.0.0

You can also use this tool to provide insights on how your APIs depend on HTTP or IBM® MQ services in an API Connect organization.

Using the API Connect Impact Analysis tool is ideal in the following common scenarios.

Scenario Description Order of attributes
Planned outage of a host Discover which APIs are unresponsive when a service host is taken down. Service – Host / QueueManager API
Upgrading the importance of an application Discover which APIs an application depends on. Application API
Upgrading the importance of an API Discover which services an API depends on. API Service – Host / QueueManager * Service – Path / Queue
Determining which service can safely be removed Discover which services are currently being used. Service – Host / QueueManager Service – Path / Queue * Application

Watch the video

Run the API Connect Impact Analysis tool

To run the API Connect Impact Analysis tool:

  1. Clone the repository from GitHub:

    $ git clone https://github.com/ChrisPhillips-cminion/APIConnect-ImpactAnalysis/

  2. Go to the directory that you just cloned, and run:

    $ npm install

  3. Within the same directory, run the application:

    $ node apicia.js

  4. Enter the server name, your user name, and your password.
  5. Select all the organizations that you want to analyze.
  6. Select the catalog that you want to view. You can select as many catalogs as you want.
  7. Select the data attributes and the order of the attributes. To customize your choices, press <space> to select, <a> to toggle all, <i> to inverse selection. You can use <left> to move an entry up or <right> to move an entry down.

    • Service – Host / QueueManager
    • Service – ContextRoute / Queue
    • API
    • Product
    • Plan
    • Application
  8. Choose whether you want to save the results. If you select yes, the tool saves them as a file in your current directory. If you select no, the tool downloads the necessary files and automatically deletes them after the analysis is completed. The results are displayed only in the command line. In the video that accompanies this tutorial, we select no.

The following example shows the results of the tool and how easily you can identify the dependencies between all APIs and their dependent services.

Sandbox
├────>  Service Host - https://httpbin.org
│    └────>  Service ContextRoute - /ip
│         ├────>  API - Demo1 : 1.0.0
│         └────>  API - testing : 1.0.0
├────>  Service QueueManager - qm1
│    └────>  Service Queue - API1IN
│         ├────>  API - Test : 1.0.0
│         └────>  API - Test 2 : 1.0.0
└────>  Service Host -  http://big
    └────>  Service ContextRoute - /DP
         └────>  API - Test_1 : 1.0.0

Run the API Connect Impact Analysis tool from a saved configuration

Instead of using the interactive prompts to configure the connection API Connect, you can use a saved configuration. To load a configuration file that has all the required details, run:

node apicia.js --load config.file

The following example shows a configuration file:

{
  "tempfolder": "tmp",
  "password": "BASE 64 Password",
  "username": "user@uk.ibm.com",
  "server": "managementserver.host.com",
  "organization": "demo",
  "catalog": {
    "sb": {
      "displayName": "Sandbox",
      "machineName": "sb"
    }
  },
  "displaySchema": [
    "Service - Server / QueueManager",
    "Service - ContextRoute / Queue",
    "API"
  ]
}

Help flags

The API Connect Impact Analysis tool has the following flags if you need assistance:

node apicia.js [--json] [--load <path>] [--help]
--load <path>         -      Load Config from path
--json                -    print the response in JSON
--help               -     this message

Conclusion

This tutorial showed how you can use the API Connect Impact Analysis tool to help you understand which services effect other services and the critical applications that use those services.

Acknowledgements

The authors thank Tom Van Oppens and Oliver Wynn for reviewing this article.