API Insights consists of two primary capabilities. The first is a set of integrations to populate the CMDB data model for APIs in a normalized manner. The second is a workspace for viewing the inventory and interacting with the data to make decisions and takes various actions.
As of May 2024, the following components are in the innovation lab for preview and feedback:
API Service Graph Connector for Kong Gateway
API Service Graph Connector for AWS API Gateway (for more information on setup, see this blog)
If you are interested in exploring API Insights during the innovation lab phase (effectively a beta release), your organization will ideally have either a Kong Gateway or AWS API Gateway in use where the data model which drives the workspace can be automatically populated from one of these integrations. The workspace is driven by data in the CMDB for APIs as describe here with formal documentation available here.
Configuring the Workspace
There are two roles delivered with the workspace. The first is a software architect (api_mgmt_architect) and the other is a software architect admin (api_mgmt_architect_admin). Access to the "Settings" tab is the primary difference between the two roles. Within the Settings tab there are the following options for an architect admin to specify or override.
Create New API
The Create New API functionality is not an option to actually author new APIs within ServiceNow, but provides the ability to initiate that process using your organization's current process. The default is "None", but you could specify to create a new Digital Interface record as part of application portfolio management if your org uses that module in ServiceNow. The external tool option allows you to add a URL to launch into an existing tool used for develop new APIs like Postman or Mulesoft.
Ownership Group
Configuration items have many "group" reference fields which represent something different to every organization. The purpose of this setting is to allow your organization to specify which of the four out of the box group attributes represent functional ownership of an API. The default is "Managed by", but could be changed to "Change", "Approval", or "Support".
Configure Workflows
In the innovation lab release, there is only one option for associating a workflow to an API specific process. This is in relation to the ability to grant or reject access to an API based on a user requesting such access. The current process of requesting access to an API creates a request task that will be passed to a subflow created by you or your organization to handle such requests according to what is appropriate for your enterprise. This could range from simply initiating email communications or you could fully automate the creation of a new API key / token and communicating that to the requestor.
The inputs for the subflow should be defined as follows if you want to test the functionality.
Subflow Inputs Required for Grant/Reject workflow
Here we can see there are three inputs. An optional "description", a required "grant", and a required "request_id". These are passed in automatically when clicking the approve or reject options for access requests.
Using the Workspace
Let's also understand some of the parts of the workspace and other dependencies they have. When you first navigate to the API Insights workspace, you should have either the software architect or software architect admin role. You will land on the Overview page as seen below.
Overview Landing Page
This page uses the Managed by group attribute by default (you can override in the settings) to show APIs where you are part of the group defined on the API CI record. Along the right side of the page are some data quality widget that expose important relationships or attributes that do not exist for certain APIs. The score indicates missing data for all APIs and not just those where the user is part of the Managed by group. In this innovation lab release, the APIs without a business application reflects a check for a direct "Provides::Provided by" relationship to a business application and is just a list. In the coming release we will add other setting options to check for business context based on how your company creates these relationships (through an application service, or possibly a digital interface, etc). We are also planning to add functionality to correct the data issue from within this experience.
The ownership group is again a reflection of checking for the attribute defined in the settings as representing functional ownership of an API (by default the Managed by group). This is important given the nature with which it drives the content of this page. Product models are also important in the API landscape because they are the version agnostic representation of an API. An example would be if you have five versions of an API, then you will likely have five version specific CIs listed. They will all be bound together by having a common product model reference resulting in the ability to view different versions of the same API from the detailed view.
Navigating through different versions from the details page
The Overview page also has a basic search functionality that looks through the API inventory to match your search strings. Results of the search give you additional functionality to compare 2 or 3 APIs, the ability to request access to an API (if a subflow is specified in the settings page), or to create a new API if one does not match your needs (also only if specified in the settings page).
Search results
Clicking on an API from any of the pages or search results will bring you to the detailed view page where you can navigate between different versions of the API (if they exist), or you can see all the resources belonging to the API and any activity happening across the platform for the API or any of its resources.
Detailed view of an API
If you continue to scroll down on the details page, you will see a graphical representation of the API and its CMDB relationships, including any business or application services.
Dependency view of the API
To reiterate, our goal with this innovation lab release is to provide some early access for feedback on the direction of the product where our initial use cases are aiming to provide visibility to your API inventory and give insights into managing the non-discoverable data important to understanding different dimensions of the data (security, ownership, health, etc). There are many additions coming for the controlled go-to-market release in Q3 of 2024 (which means we'll be closely aligning with any early adopter customers). However, we are interested in any early feedback based on the visibility the innovation lab release provides.
