Part 3 - Preparing HCP Destinations for Use By SAP Web IDE

[former_member181883]

Recap of Part 2

In Part 2 of this Introduction to SAP API Management, we looked in overview at the sequence of steps needed to:

1. Create a System
2. Expose backend services from that system as API Proxies
3. Group one or more API Proxies together into a Product (remember, the Product represents the unit of API Exposure)
4. Subscribe to one or more Products by creating an Application (remember, an Application represents the unit of API Consumption)

Now we will take something of a sideways step and do some preparatory work in order to allow API Proxies to be consumed through the template wizards in SAP Web IDE.

The steps described here are one-off configuration steps and once completed, do not need to be repeated.

Meanwhile, back in the HCP Cockpit...

In order for the Web IDE to be able to consume API Proxies created in API Management, we must set up two HCP Destinations.  One destination will be used by Web IDE at design time, and the other will be used at runtime.

So log on to your HCP Account and select Destinations from the menu on the left.

The first destination that needs to be created will be the one used by Web IDE at design time, and will connect to your API Management Dev Portal.  In other words, the Web IDE design time tools need to be able to connect to the same Portal used when consume an API Proxy.

Alternatively, this destination could connect Web IDE to some public API service such as the SAP API Hub.  In this example however, we will concentrate on connecting Web IDE to your own API Management Dev Portal through which your API Proxies are exposed for consumption.

The name you give to this Destination is not particularly important, but whatever name you choose should reflect the fact that it connects Web IDE's design time tools with your API Management (APIM) Dev Portal.

In this example, I'll call the destination Web_IDE_to_APIM_Designtime; however you are free to choose any name you consider suitable.

At this point, you might be thinking "if the actual name of the Destination is not important, then how is Web IDE able to identify the correct destination?"

This identification is done by means of the additional properties assigned to the Destination; but before we get to that detail, we must obtain the other property values needed for this destination.

HCP Destination for use by Web IDE at design time

The design time HCP destination needs the following property values:

Property Name	Value
Name	As discussed above
Type	HTTP
Description	Whatever description is appropriate for your situation
URL	Start your API Management Dev Portal (not the API Portal!) and copy the URL of the start page minus the suffix /#/shell/discover
Proxy Type	Internet
Authentication	AppToAppSSO

If we were to stop at this point, we would have a perfectly valid HCP Destination, but it would be of no use whatsoever, because we have not added the vital Additional Properties:

Now add the following two properties:

Property Name	Property Value
WebIDEEnabled	true
WebIDEUsage	api_mgmt_catalog

As you have probably worked out, the first parameter makes this HCP destination visible to Web IDE, and the second tells Web IDE that this particular system is a source of API Proxies that can be used by the template wizards.

HCP Destination for use by Web IDE Applications at runtime

As with the design time portal, you are free to choose any name you like for this destination.  In this case, we will use the name APIM_Endpoint_Trial since this the communication endpoint for external apps when connection API Management running on an HCP Trial account.  Again, choose whatever name make sense for you situation.

To find the URL of this particular destination requires a little explanation.  In this case, we are not creating an HCP destination dedicated to invoking a single API Proxy; instead, we want the URL that gives us access to all our published API Proxies.  In our case, this is simply the hostname prefix used to access any one of our API Proxies.

To find this value, connect to your API Management API Portal and select Test from the hamburger menu in the top left.  Select any Proxy name from the left side menu and then copy the protocol, hostname and port number from URL shown near the top of the screen.

Property Name	Value
Name	As discussed above
Type	HTTP
Description	Whatever description is appropriate for your situation
URL	The public port, hostname and port number of your HCP API Management service described in the paragraph above
Proxy Type	Internet
Authentication	NoAuthentication

Exactly as described for the design time HCP destination, if we were to stop at this point, this HCP Destination would be valid, but useless as far as Web IDE is concerned.

We need to add the following additional properties:

Property Name	Property Value
WebIDEEnabled	true
WebIDEUsage	api_mgmt_proxy

Some Interesting Background

When Web IDE is started, one of the configuration files your browser receives is simply called listDestinations.  This is a JSON file that contains the names of all HCP destination where the WebIDEEnabled property is set to true.  For example, it might look something like this:

listDestinations

[ {"Name":"MDC_HANA"," WebIDEUsage":"odata_xs, odata_gen",    "Description":"MDC Hana database for IoT data", "WebIDEEnabled":"true", "Path":""},   {"Name":"northwind", "WebIDEUsage":"odata_gen",    "Description":"Northwind OData Service", "WebIDEEnabled":"true",    "WebIDESystem":"NWX", "Path":"/V2/northwind/northwind.svc/"},   {"Name":"ESPM", "WebIDEUsage":"odata_gen",    "Description":"ESPM Demo OData app", "WebIDEEnabled":"true", "WebIDESystem":"ESPM", "Path":"/04d_ESPM_V1"},   {"Name":"GM6", "WebIDEUsage":"odata_abap,dev_abap,ui5_execute_abap",    "Description":"GM6", "WebIDEEnabled":"true", "WebIDESystem":"GM6", "Path":""},   {"Name":"MH1", "WebIDEUsage":"odata_abap,dev_abap,ui5_execute_abap",    "Description":"MH1 (TechEd Demo System)", "WebIDEEnabled":"true", "WebIDESystem":"MH1", "Path":""},   {"Name":"Web_IDE_To_APIM_Design_Time", "WebIDEUsage":"api_mgmt_catalog",    "Description":"Web IDE design time connection to API Management in trial HCP landscape",    "WebIDEEnabled":"true", "Path":""},   {"Name":"APIM_EndPoint_Trial", "WebIDEUsage":"api_mgmt_proxy",    "Description":"Web IDE runtime connection to API Management EndPoint in trial HCP landscape", "WebIDEEnabled":"true", "Path":""} ]

So based on the contents of this static file, we can understand how Web IDE knows which destinations it can look at in order to find API Management proxies.

However, we must also understand that this file is static!  This means that if you create a new HCP destination whilst Web IDE is running, you must restart Web IDE in order for it to receive a new copy of this listDestinations file.

Now thatthis preparatory configuration has been done, in the next document, we can look at how to consume an API Proxy using the template wizard in Web IDE.  As was mentioned in Part 2, whenever you create an Application, you are subscribing to one or more Products.  Every Application is assigned a randomly generated security token known as an "Application Key" or "API Key".

Whenever you wish to call a backend service exposed as an API Proxy, you must (almost) always provide this security token as part of the HTTP request.  I say almost always have to supply it because API Management imposes no technical requirement for an API Proxy to check for the presence of the API Key in the request.  However, it is usual for such a check to be made.  One situation in which a check for an API Key is not needed, is if you were to offer a free service to the public such as sunset and sunrise times for a given GPS location etc.

So next, let's now look at how this API Key value can be supplied when invoking an API Proxy.

Part 4 - Supplying the API Key at Runtime

Chris W