Part 4 - Supplying the API Key at Runtime

[former_member181883]

Recap of Part 3

In part 3 of this document series, we looked at how to set up a pair of HCP Destinations that allow Web IDE to access the API Proxy objects that exist within SAP API Management.  Two destinations were required: one for design time and the other for runtime.

We also saw that when Web IDE starts, your browser receives a file called listDestinations.  This file contains a JSON array in which are defined all the HCP Destinations for which the WebIDEEnabled flag is set to true.  The fact that this file is static explains the need to restart Web IDE after changes are made to any HCP Destinations used by Web IDE.

Next, we will take a look at how the security token known as the "Application Key" or "API Key" can be supplied at runtime.  This token is a 32 byte, randomly generated string that uniquely identifies the specific set of Products subscribed to by an Application.

Supplying the API Key at Runtime

Recall from Part 2 that when an you create an Application, you are creating a subscription to one or more Products; then within each Product, is/are the API proxy object/s you wish to invoke.

Unless you are offering a free, public service such as sunset and sunrise times for a given GPS location, you will want to manage, monitor and control the usage of this API Proxy.  The the highest level, way this is done is to configure the API Proxy such that it will reject all incoming requests that do not carry a valid API Key.  Therefore, the very first action that is usually performed by an API Proxy is to check for this API Key.

But before we can describe how an API Proxy would check for the presence of such a value, we first need to supply that value as part of the incoming request.

Logon on to your API Portal and select Manage from the hamburger menu in the top left.  Then from the tab menu, select Application.  Here you see a list of all the Applications people have created when they subscribed to your Products.

Select any one of the available applications and look at the overview screen.  Here you will see something like the screen shot shown below: notice the Application Key value.  This is the value that must be supplied when making any request to an API Proxy contained within this Application.

The API Key - To supply, or not to supply?  That is the question

It is important to understand that each API Proxy object is configured to make its own check for the presence of the API Key in the incoming request.  There is no system wide flag you can switch on called "Check for API Key in all incoming requests".  Such a check must be made on a "per API Proxy" basis.

Remember also that one Application can contain multiple Products, and that each Product can contain multiple API Proxies.  Since each API Proxy makes its own check for the API Key, it is therefore entirely possible that within the scope of a single Application, you could could have a mixture of API Proxies as shown in the diagram below:

• Some check for an API Key
• Some do not check for an API Key

Generally speaking, it is better to supply the API Key in all requests, even if it is not needed.  Supplying an un-needed API Key will not do any harm and increases the request size only by a few tens of bytes.

If, as the consumer of an API Proxy however, you would like to be more precise and send the API Key only when needed, it becomes necessary to identify not only when it should be sent, but also how.

Remember, in this scenario we are acting as the developer of a frontend application that consumes an API Proxy, not the developer of the API Proxy; therefore, we are now working in the Dev Portal, not the API Portal.

From your Dev Portal, select Test from the hamburger menu.

Here you will see a screen in which all the available APIs are listed.  Select the one in which you are interested and then simply press Send in the bottom right corner.

Check to see if you get 2 specific error messages:

1. A JSON response that contains the error message "Failed to resolve API Key"
2. An HTTP 401 Unauthorised status code.

If the request fails due to the absence of the API Key, you should see something like this:

IMPORTANT: The HTTP 401 Unauthorised status code is the default status code response from API Management in the event that the API Key is missing.  However, it is possible that the Proxy developer could decide to issue a different status code in the event of a missing API Key.  Although this is possible, it  is also unusual.

So we have now established that if this particular API Proxy does not receive an API Key, it will just make rude binary noises at us.  The next question then is to ask: How should the API Key be supplied - in the Query String or as an HTTP Header?

To answer this question, we must take a closer look at the details of the error message:

Response Body
{     "fault":{         "faultstring":"Failed to resolve API Key variable request.queryparam.apikey",         "detail":{             "errorcode":"steps.oauth.v2.FailedToResolveAPIKey"         }     } }

Look at the text above highlighted in red.  In this case, the error message indicates that the API Proxy is looking for the API Key as query string parameter called apikey; hence request.querystring.apikey.

Alternatively, you might see an error message like this:

Response Body
{     "fault":{         "faultstring":"Failed to resolve API Key variable request.header.APIKey",         "detail":{             "errorcode":"steps.oauth.v2.FailedToResolveAPIKey"         }     } }

In this case, the error message indicates that the API Proxy is looking for the API Key as an HTTP header field called APIKey.

It's very important to notice the subtle differences here.  In the first case, the API Proxy expects to find the API Key value in a query string parameter called exactly "apikey" (all lowercase), and in the second case, the API Proxy expects to find the API Key value in an HTTP Header field called exactly "APIKey" (mixed case).

The point here is that the variable name carrying the API Key can be called anything the proxy developer likes!

For consistency however, SAP is standardising on the sending this value as an HTTP header in a field called "APIKey".  Nonetheless, always check this error message to see exactly which variable name should be used to pass the API Key value.

So we now know:

1. Whether a particular API Proxy will fail if the API Key is missing
2. Whether the API Key should be passed as a query string parameter or as an HTTP header field
3. The name of the variable that should contain the API Key value

Now we can move on to looking at how to consume an API Proxy in Web IDE.

Part 5 - Consuming API Proxies in Web IDE

Chris W