Authors: Mridul Bhandari, Philippe Curmin, Davide Moretti

We are talking about API Discovery, a new feature of API Connect, from now available on the API Connect V10.0.8 and API Connect SaaS on AWS. 

This new feature enables to discover APIs which are not within your API Management with API Connect, either from a static source (a GitHub repository) or dynamically from actual API calls. Three different API collectors are available (GitHub, Datapower API Gateway proxy,  OpenTelemetry on Istio/NGINX), the API Manager user interface has a new “Discover” page which shows sources (collectors) and discovered APIs. A discovered API can be reviewed in the API Manager, in an interface similar to the “Develop” screen, or exported as a YAML or JSON OpenAPI file. Then a discovered API can be copied to the list of draft APIs in the “Develop” view, from where it can become a managed API, finally published into a catalog within a product. 

In this blog we are going to talk about the use cases and how to manage the unmanaged APIs, but among all the three connectors we are going to describe only the first one, the GitHub collector  (SaaS).

For the second one, the DataPower API Gateway proxy collector (SaaS), we wrote another BLOG, in parallel to this one, so if you're interested I encourage you to take look at it.

While for the third type of collector, the OpenTelemetry on Istio data source collector (SaaS), we would  like to reference to the BLOG written by our colleague Denise Mattimoe, Software Development Architect of IBM API Connect.

Use Case  

This could potentially open many business opportunities with API Connect, to many different industries and companies. For example, think about a large enterprise that runs hundreds, possible thousands of applications which rely on 4U’s APIs: unmanaged, unsecured, untested or even unused/forgotten APIs (shadow or zombie APIs), which have high potential to be non-compliant to governance standards and could even lead to security gaps and risks to the enterprise.  

This company could use the Discovery capability of API Connect to discover unmanaged REST APIs, automatically create their documentation and they can even import them into the API Manager and transform these APIs into managed APIs. They could also discover unmanaged APIs, choose to not import them into the API Manager, so let them unmanaged but still expose these APIs through the API Connect Developer Portal, where consumers can see automatically created documentation and code samples for each API.  

How to create a static data source collector using GitHub Actions workflow for API Discovery  

As already noted in the introduction the Discovery feature can discover REST APIs at runtime via the DataPower API Gateway or OpenTelemetry logs, but it also can look into GitHub repositories and discover unmanaged/unused APIs, even if they are never called. We will describe this static data source collector in this section.  

To connect the GitHub data source to the API Connect instance you will use two YAML files already provided in the IBM Documentation  (SaaS), to implement two GitHub workflows that run at every commit and check changes in the files or folders that you want to monitor, and eventually send everything to API Connect. Of course, the first run will synchronize all the APIs detected in the specified folders/files, which will then be visible on the API Connect Discovery page in the API Manager.  

Note: API Connect and GitHub are connected through an API Key that can be created inside the API Connect instance, which is saved as a repository secret inside GitHub. Be aware that the name of the secret is important since it is referenced inside the workflow YAML file, as indicated in the IBM Documentation  (SaaS).  

The Discovery page in the API Manager will be filled with all detected APIs:  

All APIs are saved along with metadata, for example the source, the version, the creation time, the URL etc.  

From here we can inspect a specific API:  

You have an overview of the API: the version of the OpenAPI standard, the protocol, the endpoint and other useful informations, along with all the operations supported and the related paths.   

 Note: in the upper right corner the blue “Copy to draft” button can be used to import this API as a draft inside the Develop section of the API Manager.  

Inside a single operation we can find more details like parameters:  

And even if it is unmanaged we can find an example of a request, an example of the body response and its data schema, as for every managed API inside IBM API Connect:  

Manage unmanaged APIs  

For any type of API Discovery source, once an API has been copied from the Discover page to the Develop page, it can be reviewed and modified by adding API security and additional policies in its assembly. Then it can be published into a product, for API lifecycle management and socialization within API Connect. Of course, It is also possible to expose a discovered API into the API Connect Developer Portal as an “unmanaged” API, in this way API consumers can access the generated documentation and code samples, but they will not be able to actually consume that API through the Portal.  

 Conclusions

Throughout this study we tested the new Discovery feature of API Connect, that enables to discover unmanaged APIs from three possible sources: one static source which is a GitHub repository, two dynamic sources which are a Datapower gateway proxy and OpenTelemetry logs on Istio/NGINX.  

In this blog we explained how we tested the first API discovery source, the static one, using APIs contained in GitHub repositories, giving additional details to those already present in the IBM Documentation  (SaaS).  

The GitHub repository data source is a great feature that is powerful and simple to use within API Connect. It can certainly bring value to clients with an existing set of APIs who can put an API Management practice in place with API Connect, or who migrate to API Connect from another solution.  

Credits  

Mridul Bhandari, Philippe Curmin, Davide Moretti