Introduction
An important aspect of API Management is analyzing and monitoring the usage of your APIs.
SAP API Management lets you monitor the usage of your APIs from several perspectives, being more technical or more business-oriented.
But sometimes, the pre-defined dashboards may not suit your needs. Therefore you can create custom dashboards, based on pre-defined metrics. However, you may also want to create dashboards based on other metrics, such as the content of the API call payload. This is possible by using a specific policy called "StatisticsCollector".
In this tutorial, we'll go through the creation of a custom dashboard, based on the content of the response of an API proxy.
The prerequisite for this tutorial, is that you are acquainted with SAP API Management, and that you have created the GWSAMPLE_BASIC API Proxy based on Holger Bruchelt's document How to use SAP API Management on HCP Trial
Note that you can stop at the "Create product" chapter, since it will ease our tutorial (no api keys required for instance).
Last but not least: you may want to use a REST tool to test you API call. Postman is a very good and free tool, that has powerful basic functionalities, and can be extended with the purchase of specific licenses. In this tutorial, I will simply use Chrome, assuming not everyone has Postman installed.
Overview
This tutorial will have 2 main steps: modifying the response flow by adding 2 policies, and creating the custom dashboard.
The "SalesOrderSet" conditional flow response will be modified in order to extract the customer name 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 amount of times each customer has been retrieved through the API proxy.
As mentioned above, I am assuming that you already have your GWSAMPLE_BASIC proxy in place in your APIM Portal. If this is not the case, please refer to the following document (until the chapter "Create product"): How to use SAP API Management on HCP Trial
1- Extract the customer name
To understand what we are doing in this step, it is good to have a look at the response of our GWSAMPLE_BASIC proxy, when calling the "SalesOrderSet" Resource.
Therefore, either use your browser or Postman (recommended!) and call the GWSAMPLE_BASIC proxy URL to get a specific SalesOrderSet. For instance:
<Your_HANA_Cloud_Platform_URL>/v1/GWSAMPLE_BASIC/SalesOrderSet('0500000005')
As you can see, the XML response looks like this:
<?xml version="1.0" encoding="utf-8"?>
<entry xml:base="https://SAPES4.SAPDEVCENTER.COM:443/sap/opu/odata/iwbep/GWSAMPLE_BASIC/" xmlns="http://www.w3.org/2005/Atom" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices">
<id>https://SAPES4.SAPDEVCENTER.COM:443/sap/opu/odata/iwbep/GWSAMPLE_BASIC/SalesOrderSet('0500000005')</id>
<title type="text">SalesOrderSet('0500000005')</title>
<updated>2016-08-17T07:38:51Z</updated>
<category term="/IWBEP/GWSAMPLE_BASIC.SalesOrder" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme"/>
<link href="SalesOrderSet('0500000005')" rel="self" title="SalesOrder"/>
<link href="SalesOrderSet('0500000005')/ToBusinessPartner" rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/ToBusinessPartner" type="application/atom+xml;type=entry" title="ToBusinessPartner"/>
<link href="SalesOrderSet('0500000005')/ToLineItems" rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/ToLineItems" type="application/atom+xml;type=feed" title="ToLineItems"/>
<content type="application/xml">
<m:properties>
<d:SalesOrderID>0500000005</d:SalesOrderID>
<d:Note>EPM DG: SO ID 0500000005 Deliver as fast as possible</d:Note>
<d:NoteLanguage>EN</d:NoteLanguage>
<d:CustomerID>0100000008</d:CustomerID>
<d:CustomerName>AVANTEL</d:CustomerName>
From the payload, we can see that the customer name is available in the "CustomerName" node.
To access this information, we will use an "ExtractVariable" policy and use an XPath expression.
To do so, open the Policy Designer by clicking on "Policies" from within your API.
Click on the "Edit" link on the right-bottom corner.
Click on the "SalesOrderSet" conditional flow 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: ExtractCustomerName
EndpointType and FlowType were set for you when you clicked on the "ProxyEndpoint>SalesOrderSet" link in the previous step
Stream: Outgoing Response
Click on "Add" to add the policy to the flow.
Use the following code to configure the Extract Policy:
<ExtractVariables async="false" continueOnError="false" enabled="true" xmlns='http://www.sap.com/apimgmt'>
<Source>response</Source>
<XMLPayload>
<Namespaces>
<Namespace prefix="d">http://schemas.microsoft.com/ado/2007/08/dataservices</Namespace>
</Namespaces>
<Variable name="CustomerName">
<XPath>//d:CustomerName</XPath>
</Variable>
</XMLPayload>
</ExtractVariables>
Click on the "Update" link at the right-bottom corner of the PolicyDesigner.
Click on the "Save" link at the right-bottom corner of the API Proxy overview.
The configuration above simply tells the policy to apply the XPath expression "//d:CustomerName", and to put the result into a custom variable "CustomerName".
On your "GWSAMPLE_BASIC" proxy homescreen, 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 and an existing sales order id:
<Your_HANA_Cloud_Platform_URL>/v1/GWSAMPLE_BASIC/SalesOrderSet('0500000005')
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 customer name is correctly extracted:
2- Add the customer name as custom metric
Now that we have extracted the customer name 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.
To do so, open the Policy Designer by clicking on "Policies" from within your API.
Click on the "Edit" link on the right-bottom corner.
Click on the "SalesOrderSet" conditional flow 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: StatisticsCollectorCustomerName
EndpointType and FlowType were set for you when you clicked on the "ProxyEndpoint>SalesOrderSet" link in the previous step
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="CustomerName" ref="CustomerName" type="string">No Customer Name</Statistic>
</Statistics>
</StatisticsCollector>
Click on the "Update" link at the right-bottom corner of the PolicyDesigner.
Click on the "Save" link at the right-bottom corner of the API Proxy overview.
The policy above simply puts the content of the "CustomerName" variable (passed in the "ref" property) into the "CustomerName" metric. The "No Customer Name" 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 meaningfull naming conventions.
3- 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 customer name metric populated with some data.
Call the following URL several times, with different SalesOrderIDs. You can vary the the SalesOrderSet number at the end from1 to 9 for instance.
<Your_HANA_Cloud_Platform_URL>/v1/GWSAMPLE_BASIC/SalesOrderSet('050000000X')
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: "SalesOrder API Calls per customer".
Select "Hits" in "Measures".
Select "customername" 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".
As you can see, your dashboard is being displayed. Change the timeline to "Hour" to see your last API calls that produced the chart.
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 pretty 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 to your dashboard. This allows for instance to create interactive dashboards for error analysis.
Furthermore, it is possible to get the analytical data over API calls, thus allowing to create your very own visualization should you have the need for it.
Any comments or questions are welcome, and I can provide the final API proxy per mail if needed.
- SAP Managed Tags:
4 Comments
