APIs are not only increasingly popular in the modern IT landscape, they are an absolute necessity in the modern IT architecture. They often serve as the backbone of Enterprise Integration Solutions, augmenting or sometimes even replacing bits and pieces of the traditional ESB. Their rise into popularity was, as so often in the IT world, accelerated by their ability to provide new business opportunities for organizations.
New business means either offering new services and products based on APIs to access realms previously unreachable due to technical incompatibilities such as Mobile Initiatives, Connected Cars, Insurance Sales or Airline Reservations – all of these are Core Business Applications running behind walls of security and utilizing legacy, but not obsolete technology.
Some companies have actually managed to productize the APIs themselves. This means selling the access to information for which consumers are willing to pay for, e.g. weather information or map directions.
The success of major modern IT initiatives is highly dependent on the success of the APIs’ development and production operations, which in turn depend on the presence of API Management software infrastructures that support APIs adoption.
It is not accidental, that major IT business analysts cover API Management for many years emphasizing its undeniable value, for example, in its latest 2016 report Gartner states that “it is impossible to … run an effective API program to benefit from the API economy, without full life cycle API management”.
Nevatech views the term “full life cycle API management” as the combination of an enterprise-class API Management that includes all of the features of API Governance. Without API Governance, there is no tracking of assets, versioning, dependency documentation or Impact Analysis within API Management, so why regard both as different disciplines?
Which components are important for API Management?
The list is extensive:
While API Management in general includes many components, there are some that are unarguably more important than others.
This priority of importance is not a Nevatech invention, it is the result of us working with an international audience over the last years. We have collected requirements and demands from API providers and consumers involved with the development and usage of APIs and can confidently state, that the most popular API Management features customers are asking for are API Monitoring and API Security.
So, you see the logical link here:
This post will focus on API Monitoring, what it actually means for technical and business people and which features organizations should expect from API Management products that offer API Monitoring capabilities.
Note, that this article is about what we have learned from our global Enterprise customers on what they were looking for in API Monitoring during their real-life endeavor into APIs.
API Monitoring from a “bird's eye view”
From a high-level perspective, API Monitoring is about capturing information from systems in general, and on APIs in particular. This can be:
purely technical information (e.g. determine API’s average response time)
business-related information (e.g. determine how many orders were placed for a particular product during the last 24 hours) or
API Monetization-related information (e.g. how often did an app use my API, which program is the developer enrolled in and how much must we now invoice).
Quite often the term “API Monitoring” is used in the context of closely related concepts, such as API Analytics, API Reporting, API Alerting or Service Level Agreements management (SLA). Those are not really API Monitoring features, because they can only act upon, or process information captured by the API Monitoring. Without API Monitoring, or with only limited API Monitoring capabilities, all other related features will not be possible, or, at best, limited. For example, if there is not enough information captured by API Monitoring, API Alerting will not be able to create and issue alerts. API Reports can be limited by the lack of available information in the first place. API Analytics may not have enough data to create technical and business analyses.
As mentioned previously, this article will focus on the discussion of information capturing, the most fundamental principle of API Monitoring.
There are four equally important perspectives needed to implement holistic API Monitoring concept itself. These are:
What information should be captured?
Where to capture information?
How to control the capture of information?
How captured information can be made available for
other API Management concepts such as API Reporting, API Analytics, API alerting, etc.
my own reporting and business analysis tools
I intend to prove importance of the items above by giving some explanations and practical examples.
What information should be captured by API Monitoring
Undeniably, the most typical pieces of information captured by API Monitoring are:
Content of the Request and Response Messages:
Message body (for example either HTTP POST message body or in non-HTTP formats, such as Microsoft SOAP NET.TCP or Azure Service Bus binary message).
HTTP headers
Complete of part of the Request URL
Timestamps of the Request and Response Messages including message exchange durations that provide means to monitor and analyze performance, and to generate alerts including those that manage SLA violations.
API caller’s identity and access claims
Username/Password
X.509 certificate
JWT (REST OAuth, OpenID Connect) or SAML (SOAP) claims
Kerberos or NTLM Window Account Name or Windows Group Membership
Custom API consumer identity (for example: Consumer API Key embedded in a custom Query Parameter or a custom HTTP header)
Other important pieces of information that must often be captured by an API Monitoring are:
Message sizes (may be required to analyze and process traffic volumes).
API caller’s IP address (may include caller’s geography derived from IP address)
Errors and error codes happened during message exchanges:
HTTP error codes
Communication errors (there may be no HTTP error codes, because the connection did not happen at all and nothing was returned from an API or its hosting server)
Business errors (there was an HTTP error with API-specific error text or error code, for example: “My API: Error 12345: customer is not found”).
In real-life and for all practical purposes, there is a lot more to that list. For example, commonly requested features from the API Management vendors are:
Capture only part of the message, not the entire Request or Response. For example: capture XML or JSON element in the request message that contains ID of the product ordered via my API, or capture multiple elements from the request but still not the entire message.
Capture API message, but do not record it in the API Management system “as is”. For example: capture request message, but record it with obscured Social Security Number (like SSN: ***-**-****), or record request message with only last 4 digits of the credit card number (like CC: *-1234)
Capture any additional custom information with message exchanges. For example, add custom information from your own database or some external system to the captured API monitoring data. Note, that this information may not be transmitted to and from an API, it may merely be added to the monitoring data to be recorded.
API Management products that provide you with the options to record all of the above-mentioned information, are the most likely to fit your API Monitoring needs. Even if you do not see the need for some API Monitoring capabilities today, choose the product that will offer you the most flexibility from day one.
Where to capture Monitoring information
This particular API Monitoring feature is quite often overlooked by organizations evaluating API Management products. To explain it, we need to look at which possibilities there are to capture API Monitoring data.
To start with, it is captured by the API Gateway, the specialized API proxy that intercepts API calls. Pretty much every API Management vendor today offers this API Management component. Among other tasks that API Gateways execute, their responsibility is to record API Monitoring data while intercepting messages and forwarding / receiving them to / from the actual backend APIs. The diagram below shows an API Gateway that intercepts request and response messages.
The tricky question is, where exactly are these messages being intercepted inside an API Gateway? The answer may be different for different products and may also affect the quality and value of the captured data for all other API Management features and integrations with your own reporting and business analytics tools.
To start with, let’s consider the same diagram above with somewhat extended view on the message capturing options.
The Request message can be captured at point 1, when it is received by an API Gateway. Then it can be captured again at point 2, when request is sent to the physical, backend API. Similarly, the Response can be captured at point 3, as soon as it is received by an API Gateway and captured again at point 4, when it is finally returned to an API client application.
Some API Gateways capture messages only at point 1 and 4, while others (like Nevatech's Sentinet Node ) captures at all 4 points. If messages are captured only at points 1 and 4, an API Gateway basically shows “the client Monitoring perspective”, which reflects the ultimate success or failure of a message exchange and provides recorded monitoring data as “seen” by an API client application.
But this may be very far from being enough, as the recording points 1,2 and 3,4 may show very different results. Here are few practical examples to illustrate why these differences are important:
Original request message is modified by an API Gateway when passing through from point 1 to point 2. This is related to the popular Message Transformation capabilities baked into many API Gateways (for example transformation from JSON to XML, or injection of a custom Query Parameter or an HTTP header). Similar considerations will apply for the Response message, as it is modified/adapted when passing through point 3 to point 4.
The ability to accurately capture both original and forwarded Request/Response messages is critical from both technical (for example, troubleshooting) and business analytics perspectives (for example, modified request contains business analytics data not available in the original request).
Errors processing and messages origination identification. When an API client receives a positive response or an error, it does not know where this response or an error originated from, from the backend API or from an API Gateway. This may be a good feature, because API clients often are not even supposed to know about backend APIs. For them, an API is where the Gateway provided an API endpoint. In other words, if an error was recorded only at point 4 and sent back to an API client, it is unknown what happened at points 2 and 3. Lack of recordings at points 2 and 3 can cause a real nightmare in the API’s troubleshooting, support and ongoing management.
Things can get even more complex when adding SOAP services to an API Management landscape. At each recording point on the diagram above, messages can be SOAP XML-encrypted, which means that API Monitoring data may need to record messages in encrypted form (exactly as they come over the “wire”) and then again in decrypted form (in clear text). This may require extending the diagram above from 4 to a maximum of 8 recording points.
Those API Management products that provide you with the options to perform API Monitoring at different recording points inside the API Gateway, are the most likely to fit your API Monitoring needs.
How to control the capture of API Monitoring information
Another important aspect of API Monitoring is API Monitoring Control. Everything discussed above is about the content of required API Monitoring data, but how to control the volume? An API Management product must provide:
Simple User Interface and User Experience to control all API Monitoring aspects. Regard the screenshot below depicting pretty much the same as the diagram above with messages recording points. This is Sentinet's actual User Interface, which offers intuitive operation of the configuration process with just a few clicks.
Control of the amount of Monitoring data to be captured at different levels, different times and based on different conditions. For example, you may need to capture different Monitoring data for different APIs, for different API operations and on a different day-time schedule. Especially important is the feature to be able to capture the entire request message only in case of specific error(s).
Asynchronous and reliable delivery of the API Monitoring data to the API Management system. The primary objective of API Management is to ensure proper management and delivery of the API business calls; if these are failing because of the failures of an API Management product itself, then why do you need that product in the first place? The same is true for API performance - business calls must be given higher priority, because they are your business. Monitoring is secondary from this perspective, and should never slow down your business message exchanges.
How API Monitoring information can be made available
You have all the Monitoring data you need in the API Management system, but how easily can the valuable information be retrieved?
An API Management solution must provide:
Easy access to the Monitoring data and its “slice-and-dice” capabilities straight from the API Management portal. This is always limited to what the vendor baked into its portal out-of-the-box such as:
Can you search data based on different search criteria (date/time, messages content, size, client identity, error codes, error messages, etc.)?
Can you group data by technical metrics and by business analytics metrics?
Can you find your own custom monitoring data in the portal?
Assured access to the Monitoring data by your own, or third-party Reporting and Business Analysis tools. For example, if monitoring data is stored in the cloud provider infrastructure, then you may not have direct access to this data. You might be given an API to access this data, but that would mean receiving raw data via API (usually more data than what you may need) and then processing that data by yourself. Access may be quite different for on-premises API Monitoring data. For example, if your Monitoring data is stored in the API Management solution's relational database on-premises, then you have direct access to it. You can run any SQL statements you want against this SQL database. You can also leverage direct integration with third-party tools that provide such integration (relational databases are again a good example here).
Secure access to the Monitoring data. Who has access to the Monitoring data, and how you can control it? Is this data in the cloud, or in the storage that you own and fully control? You may want to delegate storage management to a cloud provider, but you may also have to comply to regulations that prevent storing certain data (quite possibly related to API Monitoring) to third-parties including cloud providers.
API Monitoring is so important to enterprises because this feature allows the capture of all pertinent data to measure and manage the operations of your APIs performance and the data arriving and leaving your backend systems. Without data, there is no management and – from the board of wisdom – “if you can’t measure it, it doesn’t exist”.