SAP API Management - Creating your own status codes

[svenhuberti]

Introduction

In this article, I will describe how you can create your own HTTP status codes within SAP API Management.

Indeed, sometimes you want to send back specific HTTP status codes that are not within the scope of the standard HTTP1.1 codes. For instance, you may want to verify and alert developers about semantics in the incoming request (before hitting the backend server) or send back a specific code to developers, notifying them of runtime issues (too many requests, ...).

In order to do this tutorial on your own, I recommend that you are acquainted with SAP API, eg. that you have already created an API Proxy as described here.

Step-by-step

To generate a custom HTTP status code, we will use the Raise Fault Policy. The online documentation can be found here.

This policy lets you raise a custom fault, based on any condition within your API Proxy flows. In our example, we will throw a specific code when the spike arrest policy is kicking in: indeed, we would like our developers to handle the unavaiblaibility of the service in an elegant way.

1- Add a Spike Arrest policy

Within your API Proxy, for instance the GW_SAMPLE proxy, start by adding a SpikeArrest Policy in your request PreFlow flow ("Incoming Request"):



Name it "SpikeArrest", and remember that name for later: we will reference it in a condition.

Let's define a very low limit, so we can easily test our proxy, say 5pm ("5 per minute").

Also, you do not want the Spike Arrest policy to throw the error message: you want to continue execution, even if you are over your spike limit. We will catch that exception later in the flow, with the Raise Fault policy. Hence, set the "continueOnError" flag to "true":

<!-- This policy throttles the number of requests processed by an API Proxy protecting against performance lags and downtime -->

<SpikeArrest async="true" continueOnError="true" enabled="true" xmlns="http://www.sap.com/apimgmt">

	<Rate>5pm</Rate>

</SpikeArrest>

2- Add a Raise Fault policy

Now that we have created a SpikeArrest policy, we will add a Raise Fault policy that will inform the requester of the particular issue within the API Proxy.

Just as before, add a Raise Fault policy in your PreFlow request:



You can define several aspects in the Raise Fault policy: a header, a status response, a status code, a reason phrase, etc.. We will customize the Raise Fault exception as follows, in order to send back a meaningfull information to our requester:

<!-- can be used to create custom messages in case of an error condition -->

<RaiseFault async="true" continueOnError="false" enabled="true" xmlns="http://www.sap.com/apimgmt">

	<!-- Defines the response message returned to the requesting client -->

    <FaultResponse>

        <Set>

            <Headers/>

            <Payload contentType="application/json" variablePrefix="#" variableSuffix="%">

            {

              "errorInfo": {

                "status": "failure",

                "detail": {

                    "code": "550",

                    "text": "The API can't provide a response to you request due to too many requests. Please retry in a couple of seconds."

                    }

                }

            } 

            </Payload>

            <StatusCode>550</StatusCode>

            <ReasonPhrase>Too many requests</ReasonPhrase>

        </Set>

    </FaultResponse>

	<IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>

</RaiseFault>

As you can see, we selected the error code 550, meaning that we are raising a server error, within a custom status code space. Note the reason phrase and the payload response, which also provide meaningfull information about the error.

3- Set the condition for the Raise Fault policy

Just a for any other aspect within API Management, you can add conditions in the execution of your API proxies. The same applies to the Raise Fault policy. In our case, we want to raise a fault only of the spike arrest policy has been triggered, ie. it has not failed.

Therefore, click on your Raise Fault policy, and enter the following condition in the "Condition String" textbox:

(ratelimit.SpikeArrest.failed == "true")

Note that you need to replace "SpikeArrest" with the name of your policy.

The whole setup should look something like this:

4- Test it!

When you perform some tests, you will note that when hitting the maximum requests, you will get the following error message:



Note that I am using Postman to do the testing, but stress tools such as RESTFullStress can be handy too.

Conclusion

As you can see, it is very simple to create your own HTTP status codes. Obviously, it is a best practice to not override the existing HTTP status codes, and establish a naming convention for your own error codes.

Happy coding!