Part 9 – Assigning Policies to an API Proxy
Recap of Part 8
In Part 8 of this document series, we looked at the fact that the graphical editor known as the Policy Designer shows you only the API Policies that have been assigned to a single processing stage of the selected segment.
Now that we understand exactly what the editor is showing us, we can proceed to assign policies to the correct processing stages.
Checking for an API Key
This is probably the most fundamental check you could want to make when handling an incoming request. Log on to your API Portal, select the GWSAMPLE_BASIC proxy and then select Policies from the menu near the top right of the screen.
Remember that API Management does not perform any checks automatically! If you want the API Key (or anything else for that matter) to be checked when an incoming request arrives, then you must assign the correct policy to the correct processing stage yourself.
From the tree menu on the left side, select PreFlow underneath ProxyEndpoint, and the graphical editor will show you an empty display.
The display is empty simply because no policies have yet been assigned to either the inbound or outbound PreFlow processing stage of the ProxyEndpoint segment.
Switch into edit mode by clicking Edit in the bottom right corner of the screen.
From the Policies menu on the right, scroll down the list and click on the plus sign next to “Verify API Key”. A pop-up dialogue now appears in which we must first give this policy instance a name, and secondly, decide whether we want to assign the policy to the inbound or outbound stream in the request/response cycle.
Notice however that the processing stage (Flow Type) and segment (Endpoint Type) to which this policy is being assigned are already defined.
This decision was implicitly made when we selected PreFlow underneath ProxyEndpoint from the Flow menu on the left.
After pressing Add, you will now see that icon for the “Verify API Key” policy appears at the top of the display.
This action on its own however is not enough.
All we have done so far is to create an instance of the “Verify API Key” policy (which we have called “CheckAPIKey“) and then assign that instance to the PreFlow processing stage of the Proxy Endpoint segment.
Next we need to configure the policy instance to look for the API Key value in the correct location.
At the bottom of the screen, the editor now shows you the default contents of this policy.
|Default Contents of “Verify API Key” Policy|
<!–Specify in the APIKey element where to look for the variable containing the api key–>
<VerifyAPIKey async=’true’ continueOnError=’false’ enabled=’true’
<APIKey ref=‘variable_containing_api_key ‘/>
Notice the string highlighted in red. Here we must enter the location and variable name in which we expect to find the API Key value. By “location”, I mean that the field carrying the API Key value can be placed in either the query string or the HTTP header. When tools such as Web IDE communicate with API Management, SAP has standardised on the use of a field called APIKey (case-sensitive) in the HTTP header.
Here, we will follow the same convention.
Therefore, change this string to ‘header.request.APIKey’ so the policy now looks like this:
|Final Contents of CheckAPIKey Policy|
For the time being, we’ll assign only this one policy to the proxy, so press Update in the bottom right corner and the editor will close.
Now press Save and the Proxy will be updated.
Testing the New Policy
Now that we have assigned a policy that checks for an API Key, we have created a situation in which the Proxy cannot now be invoked without a valid API Key being present.
Let’s demonstrate to ourselves that this is indeed the case.
Having saved the Proxy, we are now looking at the Proxy overview screen in which is a list of all the collections available from this ODAta service. Against each OData collection is a set of “Get”, “Post”, “Put”, “Delete” buttons.
Press the “Get” button for the BusinessPartnerSet collection and we are now taken to the test screen for this OData service.
Simply press send, and now you see that API Management has rejected your request because it the HTTP Header was missing a field called APIKey. The “Verify API Key” policy was expecting to find a valid API Key in this field, but in this case, the entire field was missing from the request.
|Error Message Due to Missing API Key|
“faultstring”:“Failed to resolve API Key variable request.header.APIKey“,
Not only does this error message say simply that the request was rejected, but it tells us two further things:
- The status line at the bottom of the screen tells us that API Management returned a status code of HTTP 401 Unauthorised
- The text of the error message tells us exactly where the policy is looking to find the API key value. In this case, it is in an HTTP Header field called APIKey.
So let’s fix this problem.
Generating an API Key
In order to get this policy to succeed, we need an API Key. Back in Part 2 of this document series, we saw that when a user wishes to consume an API Proxy, they must go through a subscription process by creating an Application. Further to this, we saw that when creating an Application, you can only subscribe to Products and not the individual API Proxies.
Therefore, in our current situation, we must do the following things:
- Create a new Product
- Expose the GWSAMPLE_BASIC Proxy to the outside world by adding it to this Product
- Create an Application
- Consume the API Proxy (exposed through the Product) by adding the Product to the Application
Once we have created the Application, we will then have a valid API Key. This value can then be used for here for testing.
Creating a Product
Come out of the overview screen for this individual Proxy and then select Product from the menu tab in the Manage menu.
Press Create in the bottom right corner
The product can be called anything you like, but to make life simpler for ourselves, we’ll call it GW_DEMO_Data because this reflects the type of data exposed through the GWSAMPLE_BASIC OData service.
|Property Name||Property Value|
|Title||EPM Data from System ES4|
We don’t need to add anything to the “Quota”, “Requests Every” or “Scope” fields. However we do need to add the API Proxy.
At the top right of the Proxy table, click on Add. Add the GWSAMPLE_BASIC service and then press Publish in the bottom right corner.
So by adding our API Proxy to a Product, we have made it visible to the outside world (remember, a Product is the unit of API exposure). Next, and in order to generate an API Key, we must subscribe to this Product by creating an Application (remember, an Application is the unit of API consumption)
Creating an Application
In order to subscribe to a Product, we must use a different tool. We must switch from the API Portal to the Dev Portal. To do this, go back to your HCP Cockpit and from the API Management Service screen, select “SAP API Management Dev Portal”.
Once connected to the Dev Portal, select Consume from the hamburger menu and then press Create in the bottom right corner.
The Application can be called anything you like but, for simplicity, we will give it the same name as the Product – GW_Demo_Data.
Add the Product (also called GW_Demo_Data) to the Application and press Save. You are now taken back to the overview screen.
Select the newly created Application and you will now see the generated API Key. (IMPORTANT: Your API Key will be different from the value shown in the screen shot below)
Copy the API Key to the clipboard.
Test The API Proxy Again
Go back to your API Portal and go to the overview screen of the GWSAMPLE_BASIC proxy. Under the Resources section, again select the GET button next to BusinessPartnerSet collection.
Before pressing Send, click on the Headers button, add the APIKey header and paste in the value.
Click on the “Authentication: None” link in the top left and select Basic Authentication. Enter your userid and password and press OK.
You can now press Send and you will see the XML response from the OData server.
Alternative Test Tools
As an aside, it is perfectly possible to test an API Proxy using an alternative tool such as Postman. In fact, you may find it preferable to use Postman because it can store and recall test values.
A word of warning through – Postman always adds accept-language as an HTTP header to your request. If you happen to be calling a Web Service in an older SAP system, the presence of the accept-language header can cause the ABAP system to return an empty response.
In the final document, we will look at creating an API Proxy that contains a realistic amount of functionality.