SAP API Management – Custom Dashboard using Json Payload

Introduction

SAP API Management lets you monitor the usage of your APIs from several perspectives, being more technical or more business oriented. But sometimes, for a particular business use case the predefined metrics won’t be sufficient like if you would want to display a unique field (id, name etc.) captured from Json response in the APIM dashboard there is no in built metric available for it.

Therefore, to overcome this you can create something called as custom dashboards, based on unique fields from the Json response along with the pre-defined metrics. This is possible by using a specific policy called “StatisticsCollector “.

Prerequisite

The prerequisite for this tutorial, is that you are acquainted with SAP API Management, and that you have created a proxy in SAP APIM with required details. You may also want to use a REST tool to test you API call. Postman is a very good and free tool, that has powerful basic functionalities.

Overview

This tutorial will mainly focus on capturing a field from the Json response payload and then make use of the field to create a custom dashboard.

There are mainly 2 steps: modifying the response flow by adding 2 policies and creating the custom dashboard.

The “PostFlow” in ProxyEndpoint will be modified to extract the “Id” value from the response, and then will be stored as custom metric to be used in the dashboard.

After that, we’ll create a custom dashboard, that will show the number of times each Id has been retrieved through the API proxy.

Extract the userId

To understand what we are doing in this step, it is good to have a look at the response of your proxy. Therefore, either use your browser or Postman (recommended!) and call the proxy URL. For instance:

<Your_HANA_Cloud_Platform_URL>/v1/demo/users

the Json response would look something like this:

{
    "id": <<user id >>,
    "created-at": "2023-04-24T06:38:38+01:00",
    "updated-at": "2023-04-24T06:38:38+01:00",
}

From the payload, we can see that the Id is available. To access this information, we will use an “ExtractVariable” policy. To do so, open the Policy Designer by clicking on “Policies” from within your API. Click on the “Edit” link on the right-top corner.

Click on the “PostFlow” on the left-hand menu of the Policy Designer. Click on the “+” sign of the “Extract Variables” policy, on the right-handed “Policies” panel.

Name: extractUserId

Stream: Outgoing Response

Click on “Add” to add the policy to the flow. Use the following code to configure the Extract Policy:

<!-- Extract content from the request or response messages, including headers, URI paths, JSON/XML payloads, form parameters, and query parameters -->
<ExtractVariables async="true" continueOnError="false" enabled="true" xmlns='http://www.sap.com/apimgmt'>
	<!-- the source variable which should be parsed -->
	<Source>response</Source>
	<!-- Specifies the XML-formatted message from which the value of the variable will be extracted -->
	<JSONPayload>
	<!-- Specifies variable to which the extracted value will be assigned -->
	<Variable name="userId" type="string">
		<!-- Specifies the XPath defined for the variable -->
		<JSONPath>$.id</JSONPath>
	</Variable>
	</JSONPayload>
</ExtractVariables>

Click on the “Update” link at the right-bottom corner of the PolicyDesigner. Click on the “Save” link at the right-top corner of the API Proxy overview. The configuration above simply tells the policy to apply the JSONPath expression “$.id “, and to put the result into a custom variable “userId “.

On your proxy home screen, click on “Debug” on the right-top side of the screen. On the bottom-right side of the screen, start the Debug session by hitting the “Start Debug” link. Now make a call to your API proxy, using your own URL:

<Your_HANA_Cloud_Platform_URL>/v1/demo/users

On the bottom-right side of the screen, refresh your screen by hitting the “Refresh” link. You should now see the trace:

Locate your “Extract Variable” policy and check that the userId is correctly extracted:

Add the userId as custom metric

Now that we have extracted the userId into a variable, we will add it to the metric collection. This collection is available within the custom dashboards. To do that, we will use a “StatisticsCollector” policy. This kind of policy allows to collect data and have this data available as custom metric for your dashboards. Open the Policy Designer by clicking on “Policies” from within your API. Click on the “Edit” link on the right-top corner.

Click on the “PostFlow” on the left-hand menu of the Policy Designer. Click on the “+” sign of the “Statistics Collector” policy, on the right-handed “Policies” panel.

Name: stats

Stream: Outgoing Response

Click on “Add” to add the policy to the flow. Use the following code to configure the Statistics Collector Policy:

<StatisticsCollector async='false' continueOnError='false' enabled='true' xmlns='http://www.sap.com/apimgmt'>
   <Statistics>
     <Statistic name="userId" ref="userId" type="string">No Id</Statistic>
   </Statistics>
</StatisticsCollector>

Click on the “Update” link at the right-bottom corner of the PolicyDesigner. Click on the “Save” link at the right-top corner of the API Proxy overview. The policy above simply puts the content of the “userId” variable (passed in the “ref” property) into the “userId” metric. The “No Id” is the default value in case none is defined.

Note that the name of the metric will show up like this in the user interface, so it is a good practice to use meaningful naming conventions.

Create the custom dashboard

Now that we have created a custom metric, we can build our dashboard. Before we do so, lets generate some load on the API proxy so that we have the userId metric populated with some data. Call the following URL several times.

Now, navigate to the “Analyze” section of the API Management portal. The default dashboards are being displayed. To create a custom dashboard, click on the “Analyze Data” link at the bottom-right of the page:

Enter a title for the dashboard, for instance: “UserId Customer Dashboard”.

Select “Calls” in “Measures “.

Select “userId” in “Dimensions “.

Click on “Save” at the bottom-right of the screen.

Now that your custom dashboard is saved, you can display it under “Custom View”. To do so, click on the down-arrow next to the “Performance View” of the Analytics home screen, and select “Custom View “.

In this view, you can add multiple other dashboards, in order to get a specific view on your API platform.

Conclusion

As you have seen, it is easy and quick to create new, custom dashboards including custom values from your proxy. This feature is very useful to get specific insights into your API platform, whenever the pre-defined dashboards are not sufficient.

Note that it is also possible to define drill-down capabilities, simply by adding multiple measures (response time, error etc.) to your dashboard. This allows for instance to create interactive dashboards for error analysis.