Recap of Parts 3 & 4
In Part 4, we saw how a special security token known as the "API Key" or "Application Key" must often be sent as part of the request to invoke an API Proxy. We also saw how to identify whether the API Key should be sent as part of the query string or as an HTTP header field, and what variable name should be used to carry that value.
Back in Part 3, we saw how to set up two HCP destinations that between them, give Web IDE both design time and runtime access to the API Proxies created in API Management.
Now we can put these pieces together and see how to consume an API Proxy from Web IDE.
The assumption we are making here is that the API Proxy being consumed exposes an OData service. In this example, we will be consuming an API Proxy that exposes the standard demo OData service GWSAMPLE_BASIC.
Consuming API Proxies in Web IDE
To be honest, once you have exposed an OData service through an API Proxy, consuming it in Web IDE differs very little from consuming an OData service directly from a backend ABAP system. The only thing you need to do first is prepare is the HCP Destinations described in Part 3 of this document series.
Since we are going to consume the GWSAMPLE_BASIC Odata service, we know that this service presents us with (among other things) Order and Product information, therefore, we can use the Master-Detail template wizard.
Since this process is very similar to creating a Master/Detail app from any other OData service, I will not give a click-by-click account of the steps, but show only the important steps.
After selecting the correct template, we must give the app a name and then press next.
When we arrive at the screen where we choose the Data Connection, here we must chose “Service Catalog” and then select the HCP destination we just created for Web IDE at design time.
Important:
In this example, the HCP destination setup for Web IDE at design time points to your own personal API Dev Portal. Therefore, the list of visible API proxies is only those that you have configured.
Select the name of the service you wish to consume and then click on “Subscribe”.
Now we run up against a situation in which we must understand the structure of the data exposed by API Management. As we have already discovered, and in spite of the fact that we have already selected an API Proxy, it is not possible to subscribe directly to this API Proxy. The following diagram should help jog your memory:
All API Proxies are exposed by first adding them to a Product. It is only by selecting a Product that you can create an Application. But wait a minute, haven't we just done exactly the opposite of this? Well, in German, there is a very useful word to describe this situation - jein ("ja" for yes and "nein" for no squashed together)
We have indeed just selected an API Proxy without giving any consideration as to which Product (or Products) contain that API Proxy, but we have not actually subscribed to it yet.
So even though the button to move to the next screen is labelled "Subscribe", we haven't quite completed the subscription process - in fact, we're just starting it.
Remember that one API Proxy can belong to multiple Products, so at this point, we must select only one of potentially many Products to which this API Proxy could belong.
When you now click on "Select Product", behind the scenes, Web IDE creates a new Application in your API Management Dev Portal to represent this SAPUI5 application's subscription to this Product.
Now we arrive at the normal screen in which you define which fields from the exposed OData service will be used to construct the master and detail sections of the screen.
Once you finish with the template wizard, a SAPUI5 application will be generated.
But this app won't work yet. Due to the extra requirements imposed by the API Proxy, we still need to make a couple of tweaks to the configuration...
Adding the API Key to the App Descriptor file
If we stopped at this point, we would have a valid, but non-functioning SAPUI5 app.
Uh??
Yes, you read it correctly, a non-functioning app.
If our generated SAPUI5 app pointed to the OData service as exposed directly by the Gateway server, then it would work perfectly well without modification. But now we are consuming the OData service through a proxy object provided by the SAP API Management layer. In this case, we know that the API Proxy requires the presence of a valid API Key; therefore, in order to make this application functional, we have to make some modifications to the SAPUI5 app's App Descriptor file.
Locate the API Key for your Application
Log on to your API Management Dev Portal and select the newly created Application. You'll be able to recognise this application because it has the same name as the Web IDE project that consumes it.
Select the application and from the overview screen copy the API Key value.
Edit the manifest.json file
Back in Web IDE, open the application's manifest.json file and scroll down to near the end of the file. Here you will see the definition of the default model (look in the sap.ui5 --> models section for the model whose name is the empty string). After the settings property, add a new property called headers.
| Header 1 |
|---|
"sap.ui5": { ** snip ** "models": { "i18n": { "type": "sap.ui.model.resource.ResourceModel", "settings": { "bundleName": "com.sap.rig.demo.i18n.i18n" } }, "": { "dataSource": "mainService", "settings": { "metadataUrlParams": { "sap-documentation": "heading" }, "headers" : { "APIKey" : "PASTE YOUR API KEY HERE AS A QUOTED STRING" } } } }, |
Here, we have followed the SAP convention of placing the API Key value into an HTTP Header field called "APIKey".
Almost there... Now edit neo-app.json
The last piece of configuration is to tell HCP that the HTTP Header field called APIKey is safe to pass through to API Management. If we did not do this part, our SAPUI5 application would correctly send the HTTP request to API Management with the APIKey field as an HTTP header, but HCP would filter out this header field on the grounds that it has not been whitelisted and should therefore be removed.
In Web IDE, open the neo-app.json file for your application and add a new, top-level property called headerWhiteList. This property is an array containing the names of all the HTTP header fields used by this SAPUI5 application.
To make this point clear, think of it like this: HCP will filter out any HTTP header fields not listed in this array.
"headerWhiteList": ["APIKey"],
Now you can test the application knowing that the API Key is being correctly passed from SAPUI5, through HCP (without being filtered out) and on to API Management.
In the next document, we'll start to take a look at the details of API Proxies - this is now getting into the heart of API Management.
Part 6 - Overview of API Proxy Policies
Chris W
- SAP Managed Tags:
2 Comments
