SAP API Management – Support and debugging opportunities

Introduction

In a world, where everything and anything is getting connected to each other a tool to orchestrate, extend, anlayse and monetize is getting more important as it ever was. API Management (APIM) is one low-code solution to fullfill these needs on SAP Cloud Platform / SAP Business Technology Platform (SAP BTP). Even if you, your client / customer or your company does have an own API Management tool already in place, thinking about setting an ‘SAP Cloud Environment’-APIM only, to keep them in place and order, is worth it.

And then it happens … you did understand the men-in-the-middle approach APIM is following, your first proxies are in place and consumers are starting to use your proxies and coming back to you, asking for guidance and support, as their requests are starting to fail.

Understand the needs

“Can you have a look on APIM – it’s crashing” – “If it’s crashing on APIM, it’s mostly the fault of the target / consumer.”

This is a typically chat which such a consumer who has an issue with something running on APIM. But APIM isn’t hosting, it’s passing through the target. So the target is sending a ‘no success’ message, means a not 200 http status code and the consumer will get this forwarded by APIM together (hopfefully) with a response.

Me, in the role as ‘can you look at APIM please’-Support-Guy is not seeing anything at all on APIM. The only thing I see: It’s crashing (no success) and I see the http status code from the target as well. Even if I am starting the debugger, I do not see the response, I do not see the request, I do not see anything at all.

There are opportunities in place to change this, to set up debugging and supporting approaches and these ones I wanna share with you at this post.

Note: If you did enable the streaming for requests / responses all of the following opportunities will not be able to show you the requests / responses, as they will not be available on the APIM buffer if streaming is enabled (that’s actually what it is made for)

 

Opportunities

Structured replies

Starting in 2019 using APIM, I mad a lot of failures while setting up my proxies. Okay, I still make failures, but the cool thing I discovered early: SAP API Management is always sending back the same structure to the consumer:

{
    "fault": {
        "faultstring": "Invalid access token",
        "detail": {
            "errorcode": "oauth.v2.InvalidAccessToken"
        }
    }
}

A consumer will get this structure back, e.g. if the requested token was not provided, do not have access with related token-scope or the API isn’t available. So this is standard procedure by APIM.

By starting creating own nodeJS scripts and CPI iFlows providing microservices, I made sure to follow the same structure like APIM does and reuse this standard procedure. The consumer will have the same fault message structure all the time, delivered together with http status 501.

Back to topic – I want to see this fault message as well on the APIM! Most of the time, this helps me solving the issue the consumer has by ‘reading’ the fault message. Yes. Reading helps a lot!

How to do that?

As we know the response will be a JSON, we can use the ‘Extract Variables’ policy in the PostFlow of the policy:

Within that policy, we’re fetching the ‘faultstring’, ‘source’ and ‘realSource’ of the JSON-response and saving them to internal (APIM) variables. In my scenario, I am only doing that if I receive 501 as http status code from the target (nodeJS application) – so I know: It’s a consumer issue.

Before we actually can see the variables in the debugger, we need to know one important APIM behaviour: APIMs default success-http-status-codes are 2XX ( so everything starting with a ‘2’). We now need to tell APIM and this proxy, that for us http-status-code 501 is also acceptable. That’s done with success-codes of the target EndPoint (link apigee documentation):

If we’re not adding ‘501’ as acceptable ‘success.codes’, the policy we added in the PostFlow will not be executed and error.state ‘TARGET_RESP_FLOW’ with error.text ‘Received non success response code’ will be raised.

Note: The http-status-code (here: 501) and the response JSON will be forwarded to the consumer anyway. The only thing you need to know adding custom success.codes: The statistic values will change.

Now you can see the fault values from the JSON response inside the debugger:

Echo / Print

In script resources you can easily print things to the debugger Properties output of the step. Really easy for single variables:

Just “print” your variable(s) using the print() function. You will see the response in the debugger of the corresponding step:

Custom scripts

If you need to see more values like headers or the payload, you will need to add your own policies, following the first approach or writing a short javascript step. Santhosh Kumar Vellingiri did something similar already – find his approach here.

Notify someone

I am that kind of developer who wants to get informed about really hard issues as soon as possible as I want to solve them immediatley. I did this by adding a CallOut policy to the PostFlow who will call a Google-Chat webhook with a warning for me.

<!-- this policy lets you call to an external service from your API flow -->
<ServiceCallout async="true" continueOnError="false" enabled="true" xmlns="http://www.sap.com/apimgmt">
	<!-- The request that gets sent from the API proxy flow to the external service -->
	<Request>
	    <Set>
	        <Payload contentType="application/json">{"text":"Something unexpected happend, really!"}</Payload>
	        <Verb>POST</Verb>
	    </Set>
	      <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
	</Request>
	<!-- The time in milliseconds that the Service Callout policy will wait for a response from the target before exiting. Default value is 120000 ms -->
	<Timeout>60000</Timeout>
	<HTTPTargetConnection>
		<!-- The URL to the service being called | webhookToOfficerCallout is a proxy parameter you need to obtain -->
		<URL>https://chat.googleapis.com/{proxy.webhookToOfficerCallout}</URL>
         <!-- The SSL reference to be used to access the https url -->
         <SSLInfo>  
             <Enabled>true</Enabled> 
             <ClientAuthEnabled>false</ClientAuthEnabled> 
             <KeyStore/> 
             <KeyAlias/> 
             <TrustStore/> 
             <Ciphers/> 
             <Protocols/> 
         </SSLInfo> 
	</HTTPTargetConnection>
</ServiceCallout>

(Add a Condition String to the policy to execute it only if something happend (e.g. “response.status.code = 501”). So I’ll get that notification directly in google chat:

Hint: You can also use the Alert Notification Service on Cloud Foundry to collect and forward these notifications, based on context / content / values.

Conclusion

Like always – you have a lot of opportunities you can deal with and you’re able to achieve it without coding or with low-code approaches. I do recommend to set up a custom-fault-message-structure from project beginning, as it is though to set this up in an already running project where you need to update every iFlow and apps you already have.

APIM is giving you the chance to enhance things, you do not have acess to or you’re not having the ownership or – like it’s done here – to notify you with details about the things going on on your environment.