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.  You could also have set up the HCP Destination to point to the SAP API Hub, in which case you would see many, many more API Proxies.

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 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 to represent your 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.  We 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 called the OData service directly exposed from 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 Dev Portal and select the newly created Application.  This application will have 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 manifest.json file and scroll down to near the end of the file.  Here you will see the definition of the default model (this is the model whose name is the empty string).  After the settings property, add the new property headers.

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 in the 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 values used by this SAPUI5 application and that HCP should not filter out.

  "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.

Chris W

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 created 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 is 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:

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:

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

Recap of Part 6

In Part 6 of this document series, we were introduced to the idea of API Policies.

An API Policy is a container for some specific unit of functionality such as a Quota Check, or a Spike Arrest (prevents a Denial of Service attack) or some script containing custom written JavaScript or Python.  However, to be of any effect, these policies must be assigned to different processing stages in the request/response cycle.

The Agigee Edge software that powers SAP API Management divides the request/response cycle into two main segments, the Proxy Endpoint segment and the Target Endpoint Segment.  Then within each of these segments, there is the same set of two (and optionally three) processing stages.

Once you have created an instance of an API Policy and placed within it the details of your own functionality, that policy instance must then be assigned to a specific processing stage of a specific segment.

What we will look at here is how the entire request/response cycle is divided up, first into segments, then within each segment, into processing stages.

Overview of API Policy Flow Routing

The easiest way to understand the processing stages into which the request/Response cycle is divided, is by means of the diagram below.  As we move through this explanation, more and more detail will be added to the diagram; but to start with, we will simply take a high-level overview.

The incoming request originates with the client on the left hand side of the diagram.  It then follows the green arrow in a clockwise path across the top of the diagram, eventually arriving at the backend system.  The response generated by the backend system then follows the grey arrow, still moving in a clockwise direction and is passed back to the client.

During this cycle, the incoming request moves first through the processing segment called the "Proxy Endpoint", then on to the "Target Endpoint" segment.  On the way back, the outbound response moves through exactly the same processing segments, but in reverse order.

The first segment is called the Proxy Endpoint segment and it contains all the processing needed either for preparing or rejecting the incoming request.  Within this segment are at least two (often three) processing stages.

The first of these stages is called "Preflow".

Preflow is always the very first stage to be processed in any segment.  Any policies assigned to the Preflow stage are run unconditionally and are always run first.  This is where we perform the most fundamental checks on the incoming request - for instance, checking that the request contains an API Key.

If all the policies assigned to the Preflow stage run successfully (I.E. they find no reason to reject the request), then we move onto the next stage called Condition Flows.

It is possible for there to be multiple Condition Flow stages.  In fact, if you are consuming an OData service, then you will see that for every collection in the OData service, a specific Condition Flow stage has been generated.

On the inbound request side, the purpose of a Condition Flow stage it to associate a specific set of API Policies with a particular pattern in the URL.

So taking the case of an OData collection, when you perform a READ or GET operation against a collection, the URL contains first the OData service's base URL, followed by the name of the collection.  This forms a recognisable "signature" in the URL that identifies this request as being targetted to a specific collection.  The name of the collection can then be tested for in the condition string assigned to this Condition Flow.

Using the example of the BusinessPartnerSet collection in the GWSAMPLE_BASIC OData service, the Condition Flow for this OData collection has had the following condition string generated for it.  (This string has been indented and formatted for clarity.  The OData collection name is highlighted in red)

In other words if the above condition evaluates to true, then however many policies have been assigned to this processing stage will be executed.  Think of the condition string acting as a guard clause for a set of policies.  The policies will only be executed if the guard clause evaluates to true.

If the condition string attached to a Condition Flow evaluates to false, then the request processing continues on to the next Condition Flow.  If there are no subsequent Condition Flows, then we proceed to the third and final processing stage of the Proxy Endpoint segment.

If any policies are assigned to the Post Flow stage, then these are run as the last stage of processing in this segment, and are always run unconditionally.

At this point, all the processing stages of the Proxy Endpoint segment are complete and we must now decide whether or not to pass the request on to the backend system.  This is where the Route Rules come in.

The Route Rules are where must make the Go/No Go decision for routing the request to the backend system.

For instance, it is often the case that we do not want to send HTTP requests to the backend system that were made using the HTTP verb HEAD.  The HTTP verb HEAD behaves exactly like GET (in that it makes a request to the backend system for some data) except that in a HEAD request, only the HTTP headers are returned - there is no response body.  So as far as a business backend system is concerned, its usually a big waste of processing time to allow HEAD requests to hit the system.

Here's where we can filter out such requests.

The route rules are a simple set of conditions that are processed in strict sequential order.  If any route rule evaluates to false, then it is ignored and the next route rule is processed. The first matching rule wins and the rest are not processed.  Therefore, you should always place the most specific route rules first, and have the more generic one last.

If we make it through the route rules, then we can be certain that we want this request to pass through to the backend system.

Now we come to the Target Endpoint Segment.  At this point in the request/response cycle we know that the incoming request is to be passed on to the backend system, so here we perform any processing needed to prepare the request for the specific requirements of the backend system - for instance, converting the request from a set of URL parameters into an XML SOAP request body.

Here we see the same set of processing stages as are present in the Proxy Endpoint segment.

The backend system now processes the request and generates a response.  This response is picked up by API Management and again we run through the same set of processing stages as we've seen before.

Since we are now dealing with an outbound response, it makes no sense to talk about Route Rules.  Route Rules apply only to the inbound request, not the outbound response.

Finally, the response passes from the Target Endpoint segment to the Proxy Endpoint segment, and the same set of three processing stages are performed.

As you can see, the possibility exists for you to implement some very comprehensive processing within an API Proxy.

In the next document, we will look at the specific details of the individual API Policies and how they can be assigned to different processing stages in order to implement the desired functionality.

Chris W

Recap

The first 5 parts of this document series have focussed on the features and functions of API Management at a fairly high level.  Now we will start to look into the details of building an API Proxy that contains some real life functionality.

In order to proceed with this next step however, if you have not already done so, please create the following two data objects in your API Portal

1. A System pointing to SAP's public Gateway server called ES4
2. An API Proxy called GWSAMPLE_BASIC

Connecting to an ABAP Gateway Server

In order to make the following information useful in a practical sense, you should first ensure that you have an account on SAP's public Gateway server called ES4.  If you do not have an account on ES4, then please follow the sign-up instructions in this blog.

In Part 2 of this document series, there are instructions on how to create a System within API Management.  Please use these instructions to create a System called SAPDevSystemES4 that points to SAP's public Gateway server ES4.

Your new system should have these properties:

Create an API Proxy

Now that we have defined a System (an API Provider), we can now create an API Proxy that consumes a service from that system.

When creating an API Proxy, you can either enter the full URL to some publicly available service, or you can use the system details created above.  In our case, we will select the API Provider SAPDevSystemES4 and this action will then cause a "Discover >>" button to appear.  Remember back in Part 2 of this document series, we discussed the fact that when you set up a system, you can optionally add a "Catalog Service" URL.  This extra URL is now what the functionality behind the "Discover >>" button uses.  (BTW, if you press the "Discover >>" button and nothing happens, then this is probably due to the fact that the "Catalog Service" URL in the System definition is either missing or incorrect)

Pressing the "Discover >>" button causes a second popup window to appear in which you can search for the desired OData service.  Select the GWSAMPLE_BASIC service.

Having selected this service, the wizard is then able to complete all the fields in the first popup screen.

After pressing Create, we are taken to the editor overview screen.

At this point there are two important values to focus on.  Both of these values must be unique:

1. The name of the API Proxy - which in the case is GWSAMPLE_BASIC
2. The API Proxy URL - which in this case is simply /GWSAMPLE_BASIC

It is perfectly possible to create two different API Proxies that both point to the same ODAta service in the same backend system.  If you wish to do this, then you must change not only the value of the API Proxy's name, but also the API Proxy URL, since the relative URL value shown in this field will be appended to general URL for API Management related to your HCP account.

At this point, although we have not added any functionality to the API Proxy, press "Save and Deploy" down in the bottom right hand corner.

Although this API Proxy contains no functionality of its own, it is now useable.  You can demonstrate this to yourself by clicking on the "Get" button to the right of the OData collection name /BusinessPartnerSet.  You are now taken to the test screen.

Before testing this service, you need first to enter your userid and password.

Click on the "Authentication: None" link at the top left of the screen.

Select Basic Authentication

Enter your userid and password for the ES4 system and press OK.

Now press Send in the bottom right of the screen and you will see the XML response from the OData server.

So now that we have a working API Proxy, we can start to give it some functionality.

API Policies - Making your API Proxy do something useful

Each time you wish to add a unit of functionality to an API Proxy, you must make use of something called a Policy.  There are many different types of policy and each one supplies some specific unit of functionality such as a Quota Check, or a Statistics Collector or an XML to JSON transformation etc.

When we want our API Proxy to contain any sort of functionality, we must always implement that functionality by means of a policy.  You can think of a policy of the container that holds some specific unit of functionality.

Understanding How and When API Policies are invoked

Next, we must understand that within the request/response cycle handled by API Management, many policies could be invoked.  In fact if necessary, the same policy could be invoked multiple times.

In addition to these, each policy has a condition attached to it.  If the condition evaluates to true, then the contents of the policy are invoked and is the condition evaluates to false, then the functionality of that policy is bypassed.

The Policy Editor

Now we're looking into the heart of API Management - this is now where the action happens!

From you API Proxy overview screen, click on Policies link near the top right corner.

You are now taken to the Policy Editor.

This screen is divided into 4 distinct areas.  At the top centre, there is a graphical display of the Policy Flow Routing.

This diagram shows you which policies have been assigned to some specific part of the request/response cycle.

IMPORTANT: This diagram does not show you all the policies assigned to the entire request/response cycle!  There is simply not enough room on the screen to display everything, so this view shows you only part of the request;response cycle.  But more about this in the next document.

The area on the left of the screen contains a two blocks of data.  At the top is a section called Flows inside which is a tree menu.  Then at the bottom there is a section called Scripts.

Inside the Flows section, the tree menu contains two top level nodes called ProxyEndPoint and TargetEndPoint.  These two nodes represent the two main processing segments performed by API Management during a request/response cycle.  Then inside each of these segments are at least to more processing stages - Preflow, Postflow and optionally, Condition Flows.

Inside the Scripts section is a list of all the custom JavaScript, Python or XSL functionality you may have created.  In our case, this section is empty because we've only just created the API Proxy.

To the right is the list of Policies.  At the top is the list of all possible Policy Types, and underneath is a list of any policy instances you may have created.  These policy instance contain your specific functionality for a given policy type and may be assigned to any stage of any processing segment.

Finally, the bottom area of the screen holds either general documentation about the overall policy editor itself, or, when a specific policy instance is being edited, this area becomes the editor.

In the next document, we'll take a look at how we use the policy editor.

Part 7 - Understanding API Policy Flow Routing

Chris W

Hello all,

following a couple of blog entries, one of them describing how to create a Hana MDC exposing REST APIs, I want to consume my REST API through HCP SAP API Management.

After having setup a verysimple proxy, directly pointing at my XS REST Service (no destination), I am facing an authentication issue.

When calling the API proxy over a browser, I can see the MDC Login screen:

When providing my HANA MDC credentials, everything works fine.

However, when using a different client such as POSTMAN or CURL, this obviously does not work as the user interaction can't take place:

Hence my question: how do I pass credentials to my MDC backend, so that the REST API can be used in a transparent way for any application?

Thanks for any help!

Sven

Recap of Part 7

We finished Part 7 of this document series by looking at the different processing segments and stages into which API Management divides the request/response cycle.

This is very important to understand because when we now look at the tool called the API Policy Designer, the graphical display will only show us one processing stage of one segment.

Remember, the overall request/response cycle has the following segments and processing stages.

But now, when we start using the API Policy Designer, at any one time, we will only be looking at a subset of these processing stages.  Therefore we need to spend some time looking at exactly how the Policy Designer display this data.  Without this knowledge, using the Policy Designer might become somewhat confusing.

The API Policy Designer

Log on to your API Portal.  From the Manage menu option, select the GWSAMPLE_BASIC API Proxy.  Towards the top right of the screen, there is the "Policies" option.  Click here to start the Policy Designer.

Since we have not yet assigned any policies to any processing stages, the display will look like this

Remember that down the left side of the screen, there is a tree menu called Flows.  just to orientate yourself, collapse the ProxyEndpoint and TargetEndpoint tree nodes.

When you select any processing stage belonging to the ProxyEndpoint segment, you are immediately focussing on only the policies assigned to this one segment.

In other words, you are focussing on these processing stages.

Similarly, when you select the TargetEndpoint...

You are focussing only on these processing stages.

Let's now further narrow the focus by expanding the ProxyEndpoint node in the tree menu and selecting the Preflow processing stage.

In your scenario, you will see zero next to Preflow and not 3.  This is just because I'm taking screen screen shots from an API Proxy in which 3 policies have already been assigned to the Preflow stage of the Proxy Endpoint segment.

Having made this selection, the graphical display shows us only the policies assigned to these stages

Select PostFlow...

And now the graphical display shows us only the policies assigned to these stages

Finally, select one of the Condition Flows...

And now the graphical display shows us only the policies assigned to these stages

You get the idea...

So going back to the PreFlow example used above, the graphical editor will show us this.  (Don't worry that your display does not show you this - we'll fix this in the next document)

Based on the selection of PreFlow underneath ProxyEndpoint from the tree menu on the left, the editor now shows us only those policies assigned to the PreFlow processing stage of the ProxyEndpoint segment.

Similarly, by selecting PostFlow underneath ProxyEndpoint segment, the editor now shows us only those policies assigned to this processing stage of the selected segment.

So now that we understand what the editor is showing us, we can now proceed to assign some policies to the various processing stages within each segment.

Part 9 - Assigning Policies to an API Proxy

Chris W

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.

IMPORTANT!
Remember that API Management does not perform and 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 empty display simply means that at the moment, 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 and segment to which this policy is being assigned is 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 is not enough however.

All we have done so far is to create an instance of the "Verify API Key" policy 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.

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.

In this case, we will configure this policy to expect the API Key as an HTTP header field called "APIKey".

Therefore, change this string to 'header.request.APIKey' so the policy now looks like this:

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 no API Key could be found.

Not only does this error message say simply that the request was rejected, but it tells us two further things:

1. The status line at the bottom of the screen tells us that API Management returned a status code of HTTP 401 Unaathorised
2. 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:

1. Create a new Product
2. Add our GWSAMPLE_BASIC Proxy to this Product
3. Create an Application
4. Add the new Product to this Application

Once we have created the Application, we will then be given an 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 name can be called anything you like, but to make life simpler for ourselves, we'll call it GW_DEMO_Data because this reflect the type of data exposed through the GWSAMPLE_BASIC OData service.

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 we have now made our API Proxy visible to the outside world by adding it to a Product.  Next we must create a subscription to this Product in order to generate an API Key.

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 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 and under the Resources section, again select the GET button next to BusinessPartnetSet collection.

Before pressing Send, click on the Headers button and 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 your will see the XML response from the OData server.

In the final document, we will look at creating an API Proxy that contains a realistic amount of functionality.

Chris W

Recap of Part 9

In Part 9 of this document series, we looked at how the "Verify API Key" policy can be assigned to the inbound PreFlow stage of the ProxyEndpoint segment.  That's all very technical language for saying that when the request arrives at API Management, the very check to be made will be to look for the presence of an API Key.  If this check fails, then the entire request is rejected and the client receives an HTTP 401 Unauthorised response.

Now in this tenth and final document, we will look at assigning multiple policies to various processing stages, and how the outcome of one policy can be used to influence the behaviour of another policy.

For more detailed documentation on this topic, please refer to Apigee's documentation website.  From the navigation pane on the left, select Apigee Edge --> Reference and from here, you will find all the necessary documentation.

We will take the basic GWSAMPLE_BASIC proxy created in the previous document and enhance its functionality by assigning several new policies.

Since we will be testing this proxy multiple times, you may want to use a test tool such as Postman since it can store all your test parameters, whereas the built-in API Management test tool cannot.

Assigning a Quota Policy

The first addition we can make is to assign a Quote policy.  The purpose of this policy is to check that the API has not been called more than the maximum permitted number of times within a given time period.

For instance, we might decide that our API may only be called 5 times in any one-minute period; therefore we can add a Quota check to enforce this restriction.

Logon on to your API Portal, select the GWSAMPLE_BASIC proxy and start the Policy Designer.  Make sure you are in edit mode.

From the Flows menu on the left, select PreFlow underneath ProxyEndpoint.

Assign a Quota policy to this processing stage by clicking on the plus sign to the right of the Quota policy in the right-hand side list of Policies.  In this case, we will call the policy CheckQuotaLimit.

The graphical display now shows that two policies have been assigned to the PreFlow processing stage of the ProxyEndpoint segment.

In the editor at the bottom of the screen, you will now see the XML containing the default settings for this policy.

Firstly, the line highlighted in yellow creates a per-application quota check.  Without this, the API could only be called 2 times in one minute - irrespective of who was calling it.  Now that the quota is being referenced off the API Key, each user can call this API twice in one minute, irrespective of what any other user is doing.

Notice also that the instance name of the previous policy is contained in this string.  The "verifyapikey" part is the policy type and this name is fixed by API Management; however, the second part "CheckAPIKey" is the instance name of the policy we created to check the API Key.  This name must match the name of your policy instance.

Secondly, the three values highlighted in red between them define how often this API can be called.  In this case, we can see that the default settings permit only 2 calls in any one minute interval.  In our case however, we'd like to permit 5 calls per user, per minute.  Therefore, change the Allow count value from 2 to 5

Now update and save your proxy.

Testing the Quota Policy

Using your chosen test tool, add the API Key value as the HTTP header field APIKey and supply you userid and password using Basic Authentication.

Now call the API multiple times.  The first five executions will run correctly, but then the sixth execution should fail with the following message.

To test this more thoroughly, you should create a second Application (thus generating a new API Key) and then open two test screens.  Call the API using both screens and you'll find that the quota limits are API Key specific.  This demonstrates that the quota limit is working correctly.

Or is it...?

Look at the HTTP Status code that is returned after the quota limit has been exceeded.

Its an "HTTP 500 Internal Server Error".  This is not exactly the correct status code because it leads to the impression that somewhere in the server, some sort of fatal error has occurred, when in fact, all that has happened is that a quota limit has been exceeded.

Therefore, we should add a policy that sets the correct HTTP status code in the event of a quota limit failure.

Setting the Correct HTTP Status Code After a Quota Failure

Now we need to make a couple of changes.  Go back into the Policy Designer for GWSAMPLE_BASIC and make sure you are in edit mode.

Continue On Error

The first thing we need to do is tell the Quota policy to continue processing if it detects an error.  Without this, as soon as the quota limit is exceeded, the failure of the Quota policy would cause the entire request to be rejected (this is where the HTTP 500 comes from).  In this case however, we want processing to continue because will are going to create a separate policy for checking the success or failure of the Quota policy.

Look again at the configuration of the Quota policy.  We need to change the continueOnError setting (highlighted below in red) from false to true in order to prevent API Management from automatically generating the HTTP 500 status code response.

Assign a Policy For Raising A Fault

Now that we have told the CheckQuotaLimit policy to continue even if an error is detected, we must ensure that we trap that error further down the processing chain.  Therefore, we need to assign a specific "Raise Fault" policy to the PreFlow processing stage.

Click on the plus sign next to the "Raise Fault" policy and create a new policy instance called HandleQuotaError.

The graphical display now looks like this

We now want to invoke the HandleQuotaError policy only if the previous CheckQuotaLimit policy has failed.  We can do this by adding a condition string to the HandleQuotaError policy.  This condition string tests the failed flag belonging to the previous policy; therefore, we must ensure that we enter the name of the previous policy correctly.

The policy for checking the quota limit is called CheckQuotaLimit; therefore add the following condition string to the HandleQuotaError policy:

(ratelimit.CheckQuotaLimit.failed = "true")

Our HandleQuotaError policy will now only be executed if this condition is true.

Now look at the contents of the HandleQuotaError policy.  Here we need to do a few things:

1. We need to set the correct HTTP header to inform the browser how long it should wait before retrying this request
2. We need to set the HTTP status code and error message
3. We can optionally define a payload to contain a more informative error message.

The following XML accomplishes these tasks.  The changed parts are highlighted in red.

Paste this XML into your HandleQuotaError policy, then save and update your policy.

Now, when you test this policy again, the sixth execution will cause an "HTTP 429 Quota Limit Exceeded" message and a response body containing the text "Your quota has been exceeded".  Also, look at the returned HTTP Headers.  There is now one called Retry-After field containing the number of seconds after which the browser should try the request again.

Masking Internal Server Names

Finally, we will use a policy that parses the outbound response from the backend server, and changes internal server names to the public, proxied external names.  Unfortunately, there is no specific policy that can do this for us, so we will need to use a generic JavaSCript policy to invoke a few lines of JavaScript code.

So, back in edit mode in the Policy Designer, from the Flow menu select PostFlow underneath ProxyEndpoint.  This is because we want this policy to run during the last processing stage before the response is sent back to the client.

From the Policies menu on the right side of the screen, click on the plus sign next to JavaScript and call the new policy instance MaskServerName.

Notice to which Steam this policy is being assigned - the Outgoing Response.  We want this policy's processing applied to the response, not the request.

Now the graphical display will look like this:

Now look at the editor for this JavaScript policy.  What do you notice?  There's not a line of JavaScript code any where in sight - in fact it's all XML.

The point here is that this XML allows you to reference a variety of JavaScript files (that we'll create in just a minute).  By default, two JavaScript file names are assumed helper.js and maincode.js - neither of which we are going to use.

Delete the two lines highlighted in yellow and where you see maincode highlighted in red, change this to urlRewrite.

Your JavaScript policy will now look like this:

Next, we need to create the JavaScript file we've just referenced.  To do this, look in the bottom left corner of the Policy Designer screen and underneath the Flows section, there is another section called Scripts.  Click on the plus sign next to scripts and in the popup window enter the name urlRewrite.

Notice what is missing from the file name - there is no .js extension.  Do not attempt to add this file name extension because it will be added for you based on the fact that the file is of type JavaScript.

Once, you've pressed Add, you will be shown an empty editor screen.  Into this empty file, copy and paste the following code:

The first statement uses function chaining to do following 4 things all in one statement:

1. Create a variable called newpath
2. Fetch the contents of Apigee's standard context variable response.content (no prizes for guessing what this variable contains...)
3. Use a regular expression to scan for the server name and port number "SAPES4.SAPDEVCENTER.COM:443" and replace it with the server name and portnumber of API Management running in the HCP Trial landscape "trial.apim1.hanatrial.ondemand.com"
4. Use a second regular expression to replace the standard OData pathname used in ABAP systems with the HCP account name

Once these steps have been completed, the response variable response.content is replaced with the contents of the newpath variable.

In your case, you will need to obtain the external URL of your API Management system.  To do this, open a new browser tab/window and logon to your API Portal again.  Select any API Proxy and go to the overview screen.  At the top of this screen, you'll see the public URL to this API.  Copy and paste out the following parts:

Into the above regular expression, you will need to paste in the correct values for your API Management server name and port number, and also you HCP account name.

Now save and update your API Proxy.

Testing Server Name Masking

Go back to you test tool and make a not of the XML response that you are currently seeing.  It will look something like this:

After server name masking has been implemented, it will look like this:

Conclusion

This document series has spent quite a long time covering the foundational concepts of API Management and how the various tools work.  The reason for this is very simple - a building can be no stronger than its foundations.

Hopefully, you are beginning to see the potential for how much functionality could be packed into a single API Proxy.  To be honest, we've hardly scratched the surface of what API Management can do.  For instance, you could create an API Proxy that does all of the following things:

1. Receives a simple URL in which all the parameters are in the query string
2. Unpacks the query string parameters and HTTP header fields into internal variables
3. Checks whether this combination of input parameters has been seen before, and if it has, generates a response from an internal cache rather than hirtting the backend.
4. If either the combination of input parameters has not been seen before, or the cache has expired, a SOAP XML body is constructed using the values from the query string and sen to the Web Service backend
5. The XML response from the Web Service backend is cached
6. The XML response is also unpacked into a JSON string and returned to the client

There are many, many more things API Management could do for you, and I trust this document series has laid a sufficiently solid foundation for you to start building your own power API Proxies.

Have fun!

Chris W

SAP API Management Introduction

The following ten documents form an introduction to API Management

Part 1 - Introduction to API Management

Part 2 - Overview of SAP API Management Tools

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

Part 4 - Supplying the API Key at Runtime

Part 5 - Consuming API Proxies in Web IDE

Part 6 - Overview of API Proxy Policies

Part 7 - Understanding API Policy Flow Routing

Part 8 - Understanding the API Policy Designer

Part 9 - Assigning Policies to an API Proxy

Part 10 - Assigning Multiple Policies to an API Proxy

On this page we want to provide you with an overview of available documentation / how-to guides / tutorials / ... that help you get started with SAP API Management on HCP.

Official Documentation

• https://help.hana.ondemand.com/apim_od/frameset.htm
• API Management | Application Programming Interface | SAP
• API Management | SAP HANA Cloud Platform
• SAP API Management Technical Brief (download) /SAP API Management - Cloud Technical Brief (display)
• Solution Brief: SAP API Management (cloud offering)

Introduction / Getting Started

• Free Trial of SAP API Management on HANA Cloud Platform is available now!
• How to use SAP API Management on HCP Trial
• Building & Consuming APIs using SAP API Management (Part 1)
• Building & Consuming APIs using SAP API Management (Part 2)
• Exposing Digital API’s using HCP Trial - API Management Service
• SAP API Management - Hands-On Material
• SAP API Management Introduction - Index Page

Connecting Systems

• SAP API Management – Using Cloud Connector
• Expose Gateway Services via HCI OData Provisioning, and secure them using SAP API Management on HCP Trial - Part 1
• Expose Gateway Services via HCI OData Provisioning, and secure them using SAP API Management on HCP Trial - Part 2

Creating APIs

Working with Policies

• SAP API Management – Policy Management
• SAP API Management - Understanding Policy Flow
• SAP API Management - Enabling URL masking
• SAP API Management – SOAP to REST

Analytics

• Analytic's on API Portal

Consuming APIs

• Consuming APIs from Web IDE via SAP API Management

IoT and other related Scenarios

• Internet of Things made simpler with SAP API Management Part I - Overview, Part II - HCP IoT Service , Part III - IoT APIs via SAP API Management
• SAP API Hub (Beta) available on HANA Cloud Platform Trial
• How to use SAP API Hub (Beta)
• A more fun API to manage and build an App on top of

If you have are missing anything or have other feedback, please let us know! You can contact us via E-Mail or leave a comment.

Introduction

In this tutorial, I will explain how to expose a SOAP WebService as a REST API.

The prerequisite for this tutorial, is that you are acquainted with SAP API Management, eg. that you have already created some API proxies like described in Holger Bruchelt's document How to use SAP API Management on HCP Trial

This proxy can be created on the SAP API Management Trial environment.

For the purpose of the tutorial, I will use a public web service called "Calculator" that is available here. This WebService allows to execute mathematical operations. In our case, we will hardcode the "add" operation.

If you are interested in getting a working proxy, that you can import into your environment, feel free to reach out to me.

Overview

First of all, note that with an API Proxy, you can access a web service either by setting up the backend to be the target of your proxy, or by making a so called "Callout" from within the proxy. In our tutorial, we will use the WebService as target backend.

Before we get our hands dirty, let's see what our master plan is. The diagram below is a view of what we'll do in this tutorial:

1- Create the API proxy: we will create a proxy that will expose the "Calculator" WebService as a REST API, that can be reached over "<SAP HCP APIM URL>/v1/calculator", using the calculator web service as target backend.

API Proxy Request flow:

2- Generate the SOAP request: SOAP WebServices requires specifically formatted requests. The REST API we'll provide is easier to use, and only requires 2 query parameters. To map these parameters to the specific SOAP WS request, we will generate the request using an "Assign Message" policy.

Response:

The web service response is an XML response, with a lot of metadata, that is not always useful to the REST API consumer. JSON has proven to be an ideal notation for apps or web applications, being lightweight, simple to understand and to use. For these reasons, we will convert the XML response into JSON, and remove the metadata, so that the REST API is easy to use and lightweight.

To achieve this we will:

3- Convert the response to JSON: with a "XML t oJSON" policy, the XML response will be converted to JSON,

4- Beautify the response: with an "Extract Variables" policy, we will extract the desired information from the JSON, add set it as the API proxy response.

1- Create the API Proxy

Log into your Hana Cloud Cockpit, and navigate to the "API Management" Service.

In the APIM Dashboard, select "Quick Actions" > "Create Artifacts" > "API":

In the API Proxy creation window, enter the details as follows:

API Provider: None

URL:http://ws1.parasoft.com/glue/calculator

Name: Calculator

Title: Calculator

Description: This API will execute mathematical operations

API base path: /v1/calculator (it is a best practice to always add a version to the base path of your API)

Service Type: REST

Hit the "Create" button, and then "Save and deploy".

2- Generate the SOAP request

When calling our REST API, we will use 2 parameters, Number1 and Number2. These will be the number used for the addition the service will make, for instance:

The response of /v1/calculator?Number1=10&Number2=30 will be 40

In order to place a SOAP call, we need to generate a SOAP request. This SOAP request has a specific structure, with specific headers and XML payload, containing the request parameters.

To do so, open the Policy Designer by clicking on "Policies" from within your API.

Click on the "Edit" link on the right-bottom corner.

Click on the "ProxyEndpoint>PreFlow" on the left "Flow" panel.

Click on the "+" sign of the "Assign Message" policy, on the right-handed "Policies" panel.

Name: GenerateSOAPRequest

EndpointType and FlowType were set for you when you clicked on the "ProxyEndpoint>PreFlow" link in the previous step

Stream: Incoming Request

Click on "Add" to add the policy to the flow.

The "Assign Message" policy is very powerful, and lets you assign values to headers, query parameters, payload, custom variables, etc.. In our case, we will use it to define the required SOAP call, dynamically created using our query parameters.

Replace the XML configuration of your Assign Message policy with the following:

<AssignMessage async="false" continueOnError="false" enabled="true" xmlns='http://www.sap.com/apimgmt'>    <Set>        <Headers>            <Header name="SOAPAction">add</Header>            <Header name="Content-Type">text/xml; charset=utf-8</Header>        </Headers>        <Payload contentType="text/xml">            <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">                <soap:Body>                    <add xmlns="http://www.parasoft.com/wsdl/calculator/">                        <!--Required-->                        <x>{request.queryparam.Number1}</x>                        <!--Required-->                        <y>{request.queryparam.Number2}</y>                    </add>                </soap:Body>            </soap:Envelope>        </Payload>        <Verb>POST</Verb>    </Set>    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>    <AssignTo createNew="false" transport="http" type="request"/></AssignMessage>

Note that the AssignMessage policy will:

- create 2 headers,

- create the XML payload as required by the web service,

- set the "Verb" to POST since all SOAP transactions are "POST".

This configuration is then assigned to the request that will go to the backend, ie. the Calculator web service.

Also note that we are dynamically setting the parameters "x" and "y" that are required by the web service endpoint, using a specific notation: the curly brackets mean that we reference the value a flow variable: "{<var_name>}". This flow variable is either user-defined, and set by using an "Assign Message" policy, or pre-defined, and set during runtime.
In our case, we use a pre-defined variable called "request.queryparam" and append the name of the query parameter we want to retrieve. At runtime, "{request.queryparam.Number1}" will be replaced by the value of the query parameter "Number1".

Click on the "Update" link at the right-bottom corner of the PolicyDesigner.

Click on the "Save" link at the right-bottom corner of the API Proxy overview.

It's a good idea to test the proxy now. To do so, simply open a browser window (preferably Chrome) and paste the URL of your proxy. Add the parameters "Number1" and "Number2" to your request and run the query.

As you can see, the request is passed to the SOAP backend, which returns the XML data according to your query parameters.

However, as an app developer, I would love to have that information in a lightweight and simple-to-use format: JSON. Therefore we will convert and beautify the response.

3-Convert the response to JSON

Converting XML data to JSON is very simple with SAP API Management. You only need to add a "XML to JSON" policy on the response flow of your proxy.

To do so, open the Policy Designer by clicking on "Policies" from within your API.

Click on the "Edit" link on the right-bottom corner.

Click on the "ProxyEndpoint>PreFlow" on the left "Flow" panel.

Click on the "+" sign of the "XML to JSON" policy, on the right-handed "Policies" panel (you may need to scroll down to see the policy).

Name: XMLtoJSON

EndpointType and FlowType were set for you when you clicked on the "ProxyEndpoint>PreFlow" link in the previous step

Stream: Outgoing Response

Click on "Add" to add the policy to the flow.

The "XML to JSON" policy can be configured in several ways to fit your needs. In our case, we simply specify that the text for an empty node name is "value".

Use the following configuration for your policy:

<!-- This policy converts an XML payload to JSON structure --><XMLToJSON async="false" continueOnError="false" enabled="true" xmlns='http://www.sap.com/apimgmt'>  <Options>    <TextNodeName>value</TextNodeName>  </Options>  <!-- The variable to which the converted JSON should be assigned to -->  <OutputVariable>response</OutputVariable>  <!-- The variable that we want to convert to JSON -->  <Source>response</Source></XMLToJSON>

Click on the "Update" link at the right-bottom corner of the PolicyDesigner.

Click on the "Save" link at the right-bottom corner of the API Proxy overview.

Test your proxy again using the previous URL.

The response of the proxy now looks much simpler and easier to consume:

4- Beautify the response

Even though the response is now lightweight and easy to use, let's improve it even more (this is not a necessity, but a good excuse to have a look at another policy!).

Just as there is XPath for XML, there is JSONPath for JSON. SAP API Management provides an "Extract Variables" policy that can execute a JSON path expression against JSON payload.

Our current response payload looks like this:

{  "Envelope":{      "Body":{        "addResponse":{              "Result":{                "type":"xsd:float",              "value":"35.0"            }        }      }  }
}

What we would like to end up with, is only the "addResponse" code:

{      "Result":{            "type":"xsd:float",          "value":"35.0"    }
}

We will use the following JSONPath expression: "$.Envelope.Body.addResponse" that points at the "addResponse" element of our payload, starting from the root ("$").

To do so, open the Policy Designer by clicking on "Policies" from within your API.

Click on the "Edit" link on the right-bottom corner.

Click on the "ProxyEndpoint>PreFlow" on the left "Flow" panel.

Click on the "+" sign of the "Extract Variables" policy, on the right-handed "Policies" panel (you may need to scroll down to see the policy).

Name: GetResponseOnly

EndpointType and FlowType were set for you when you clicked on the "ProxyEndpoint>PreFlow" link in the previous step

Stream: Outgoing Response

Click on "Add" to add the policy to the flow.

Use the following code the configures the execution the above JSONPath:

<ExtractVariables async="true" continueOnError="false" enabled="true" xmlns='http://www.sap.com/apimgmt'>    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>    <JSONPayload>        <Variable name="response.content">            <JSONPath>$.Envelope.Body.addResponse</JSONPath>        </Variable>    </JSONPayload>    <Source>response</Source></ExtractVariables>

The policy above executes the JSONPath against the source "response", and sets the value of the result into the variable "response.content". This variable is a predefined variable, and contains the response of the API proxy. We are actually overwriting the response, with the result of the JSONPath expression with our policy.

Click on the "Update" link at the right-bottom corner of the PolicyDesigner.

Click on the "Save" link at the right-bottom corner of the API Proxy overview.

Test your proxy again using the previous URL.

Final words

As you may have seen throughout this tutorial, SAP API Management provides the ability to quickly and simply adapt a web service to expose it as REST API, and adapt it to your specific needs. I hope that even if we only have scratched the surface, you got an idea of what is possible, and that you'll have fun in the future using HCP SAP APIM!

For any questions or comment feel free to contact me or to leave a comment below.

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:

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:

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.

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:

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:

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 that this 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

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:

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:

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

Hi,

Have been reading on the API management and its usage specifically around integration web or mobile devices either directly or with the usage of PI or HCI.

My question specifically is are there any APIs exposed on HCP that the application ( SFSF or Ariba or S4Hana etc ) can exclusively use it ( not to exchange but to use within the application.

If yes, please do state an example that will help me to understand this better

E.g: In Successfactors, Performance management we have an API that takes care of employee appraisal. Is this something that is done through API or no?

Many thanks,

Venkat.

Introduction

"API Management is not SOA": that also means that an API Management layer should not perform complex data massage. However you may want to enhance your APIs with contextual information.

For instance, a business partner API response could be enriched with geo-coding data, providing the App Developer the useful data to locate a business partner on a map in the UI. But you could also add the weather for a location request, a stock price for a customer request, etc.. Remember that API Management is also about making your customer happy and productive, in this case the App Developer!

So how does that work within SAP API Management?

In this tutorial I will explain how to get geo-coding information from a public REST API (Google) based on the backend response, and add that information into the API Proxy response.

The prerequisite for this tutorial, is that you are acquainted with SAP API Management, and that you have created the GWSAMPLE_BASIC API Proxy based on Holger Bruchelt's document How to use SAP API Management on HCP Trial

Note that you can stop at the "Create product" chapter, since it will ease our tutorial (no api keys required for instance).

Last but not least: you may want to use a REST tool to test you API call. Postman is a very good and free tool, that has powerful basic functionalities, and can be extended with the purchase of specific licenses. In this tutorial, I will simply use Chrome, assuming not everyone has Postman installed.

Overview

In this tutorial, we will modify the response of the "BusinessPartnerSet" Resource by adding geocoding information to the address object. We will work with JSON objects since they are easy to work with for the App Developer. Note that you could query the OData service with the header "accept" set to "application/json" to get the response back directly in JSON, but for educational purpose, we'll do that in our API Proxy.

Here is an overview of the proxy we'll create:

As mentioned above, I am assuming that you already have your GWSAMPLE_BASIC proxy in place in your APIM Portal. If this is not the case, please refer to the following document (until the chapter "Create product"): How to use SAP API Management on HCP Trial

1- Convert the response to JSON

The first thing to understand, is that we will work with the conditional flow "BusinessPartnerSet". A conditional flow is executed after the pre-flow, and before the post-flow. This pattern applies both the the request and response. Please check the documentation or the excellent blog entry from Elijah Martinez for more detailed information.

Log into your Hana Cloud Cockpit, and navigate to the "API Management" Service.

Navigate to the list of your APIs through the "APIs" Tile.

Click on the "GWSAMPLE_BASIC" API proxy.

Click the "Policies" link In the proxy overview to open the Policy Designer.

Click on the "BusinessPartnerSet" conditional flow on the left-hand menu of the Policy Designer.

Note that this conditional flow will apply only if the condition "Flow condition" is met. But also note, that only the first conditional flow encountered will be executed.

Click on the "Edit" link on the right-bottom corner.

Click on the "+" sign of the "XML to JSON" policy, on the right-handed "Policies" panel (you may need to scroll down to see the policy).

Name: XMLtoJSON

EndpointType and FlowType were set for you when you clicked on the conditional flow in the previous step

Stream: Outgoing Response

The "XML to JSON" policy can be configured in several ways to fit your needs. In our case, we do not need to adapt the output so we will simply remove the content of the "Options" tag.

Use the following configuration for your policy:

<!-- This policy converts an XML payload to JSON structure --><XMLToJSON async="false" continueOnError="false" enabled="true" xmlns='http://www.sap.com/apimgmt'>    <Options>  </Options>  <!-- The variable to which the converted JSON should be assigned to -->  <OutputVariable>response</OutputVariable>  <!-- The variable that we want to convert to JSON -->  <Source>response</Source></XMLToJSON>

Click on the "Update" link at the right-bottom corner of the PolicyDesigner.

Click on the "Save" link at the right-bottom corner of the API Proxy overview.

Use a browser or Postman to test your API Proxy: <Your_HANA_Cloud_Platform_URL>/GWSAMPLE_BASIC/BusinessPartnerSet

You should get the following response:

Note that this is the list of all partners, however we will pick only one for our code to work.

Add the ID of the partner to the URL: <Your_HANA_Cloud_Platform_URL>/GWSAMPLE_BASIC/BusinessPartnerSet('0100000000')

NB: because the JSON may not be not formatted properly if you are using Chrome, it may not be easy to read. You may want to use an online tool to beautify your JSON: https://jsonformatter.curiousconcept.com/

{   "entry":{      "etag":"W\/\"datetime'2016-06-30T21%3A31%3A20.0000000'\"",      "base":"https:\/\/SAPES4.SAPDEVCENTER.COM:443\/sap\/opu\/odata\/iwbep\/GWSAMPLE_BASIC\/",      "id":"https:\/\/SAPES4.SAPDEVCENTER.COM:443\/sap\/opu\/odata\/iwbep\/GWSAMPLE_BASIC\/BusinessPartnerSet('0100000000')",      "title":{         "type":"text",         "":"BusinessPartnerSet('0100000000')"      },      "updated":"2016-07-01T12:29:41Z",      "category":{         "term":"\/IWBEP\/GWSAMPLE_BASIC.BusinessPartner",         "scheme":"http:\/\/schemas.microsoft.com\/ado\/2007\/08\/dataservices\/scheme"      },      "link":[         {            "href":"BusinessPartnerSet('0100000000')",            "rel":"edit",            "title":"BusinessPartner"         },         {            "href":"BusinessPartnerSet('0100000000')\/ToSalesOrders",            "rel":"http:\/\/schemas.microsoft.com\/ado\/2007\/08\/dataservices\/related\/ToSalesOrders",            "type":"application\/atom+xml;type=feed",            "title":"ToSalesOrders"         },         {            "href":"BusinessPartnerSet('0100000000')\/ToContacts",            "rel":"http:\/\/schemas.microsoft.com\/ado\/2007\/08\/dataservices\/related\/ToContacts",            "type":"application\/atom+xml;type=feed",            "title":"ToContacts"         },         {            "href":"BusinessPartnerSet('0100000000')\/ToProducts",            "rel":"http:\/\/schemas.microsoft.com\/ado\/2007\/08\/dataservices\/related\/ToProducts",            "type":"application\/atom+xml;type=feed",            "title":"ToProducts"         }      ],      "content":{         "type":"application\/xml",         "properties":{            "Address":{               "type":"\/IWBEP\/GWSAMPLE_BASIC.CT_Address",               "City":"Walldorf",               "PostalCode":"69190",               "Street":"Dietmar-Hopp-Allee",               "Building":"16",               "Country":"DE",               "AddressType":"02"            },            "BusinessPartnerID":"0100000000",            "CompanyName":"SAP",            "WebAddress":"http:\/\/www.sap.com",            "EmailAddress":"do.not.reply@sap.com",            "PhoneNumber":"0622734567",            "FaxNumber":"0622734004",            "LegalForm":"AG",            "CurrencyCode":"EUR",            "BusinessPartnerRole":"01",            "CreatedAt":"2016-06-30T21:31:20.0000000",            "ChangedAt":"2016-06-30T21:31:20.0000000"         }      }   }
}

The API callout we will make in the coming steps requires an address in order to provide the geographical coordinates. In the next steps, we will build the address using the "street", "city" and "country" information from the JSON response (see the object entry.content.properties.Address above).

To do that, we will now use the "Extract Variable" policy.

2- Extract the partner address

As explained above, we need to get the address information from the JSON payload. We can extract the required information easily, using en "Extract Variable" policy, that will execute some JSONPath expression against the response payload.

To do so, open the Policy Designer by clicking on "Policies" from within your API.

Click on the "Edit" link on the right-bottom corner.

Click on the "BusinessPartnerSet" conditional flow on the left-hand menu of the Policy Designer.

Click on the "+" sign of the "Extract Variables" policy, on the right-handed "Policies" panel.

Name: GetPartnerAddress

EndpointType and FlowType were set for you when you clicked on the "ProxyEndpoint>PreFlow" link in the previous step

Stream: Outgoing Response

Click on "Add" to add the policy to the flow.

Use the following code to configure the Extract Policy variable:

<!-- Extract content from the request or response messages, including headers, URI paths, JSON/XML payloads, form parameters, and query parameters --><ExtractVariables async="true" continueOnError="false" enabled="true" xmlns='http://www.sap.com/apimgmt'>    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>    <JSONPayload>        <Variable name="city">            <JSONPath>$.entry.content.properties.Address.City</JSONPath>        </Variable>        <Variable name="street">            <JSONPath>$.entry.content.properties.Address.Street</JSONPath>        </Variable>        <Variable name="country">            <JSONPath>$.entry.content.properties.Address.Country</JSONPath>        </Variable>    </JSONPayload>    <Source>response</Source></ExtractVariables>

Click on the "Update" link at the right-bottom corner of the PolicyDesigner.

Click on the "Save" link at the right-bottom corner of the API Proxy overview.

Some explanations about our "Extract Variable" policy. It will execute the 3 JSONPath expressions on the backend response (set in the element "Source"), and create/populate so called "flow variables". These will hold the "city", "street" and "country" information which in turn can be used from any policy within the resting response flow.

To see if this has worked, we'll look at the execution trace of our proxy through the "Debug" screen.

On your "GWSAMPLE_BASIC" proxy homescreen, click on "Debug" on the right-top side of the screen.

On the bottom-right side of the screen, start the Debug session by hitting the "Start Debug" link.

Now make a call to your API proxy, using your own URL and an existing partner id: <Your_HANA_Cloud_Platform_URL>/GWSAMPLE_BASIC/BusinessPartnerSet('0100000000')

On the bottom-right side of the screen, refresh your screen by hitting the "Refresh" link.

You should now see the trace:

The second policy towards the API Proxy requester, is our Extract Variable policy. Click on it to display the execution details.

Scrolling down the details page, you will see the result of the execution, containing the variables we are setting:

It all worked fine, and we have now 3 variables containing the address information of the partner we requested.

In the next step, we will use these variables to create the geo-coding API callout.

3- Call the geo-coding API

In order to get the geocoded address (latitude and longitude) of our partner, we will use Google's geocoding service.

It is available for free to anyone, and can be reached over the following URL:

https://maps.googleapis.com/maps/api/geocode/json?address=<address>

For example: https://maps.googleapis.com/maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View

We will set the partner address as parameter to be sent to google in our "Service Callout" policy.

To do so, open the Policy Designer by clicking on "Policies" from within your API.

Click on the "Edit" link on the right-bottom corner.

Click on the "BusinessPartnerSet" conditional flow on the left-hand menu of the Policy Designer.

Click on the "+" sign of the "Service Callout" policy, on the right-handed "Policies" panel.

Name: GetLatLong

EndpointType and FlowType were set for you when you clicked on the "ProxyEndpoint>PreFlow" link in the previous step

Stream: Outgoing Response

Click on "Add" to add the policy to the flow.

In the policy configuration, use the following configuration to make the callout:

<!-- this policy lets you call to an external service from your API flow --><ServiceCallout async="true" continueOnError="false" enabled="true" xmlns="http://www.sap.com/apimgmt">  <!-- The request that gets sent from the API proxy flow to the external service -->  <Request/>  <!-- the variable into which the response from the external service should be stored -->  <Response>LatLongResponse</Response>  <!-- The time in milliseconds that the Service Callout policy will wait for a response from the target before exiting. Default value is 120000 ms -->  <Timeout>30000</Timeout>  <HTTPTargetConnection>  <!-- The URL to the service being called -->  <URL>https://maps.googleapis.com/maps/api/geocode/json?address={street},{city},{country}</URL>  </HTTPTargetConnection></ServiceCallout>

As you can see within the configuration, we are making a call against Google's geocoding API dynamically, setting the "address" parameter to be the flow variables we created and populated in the previous steps.

Note that the content of flow variables is referenced in the configuration of policies, using curly brackets: {myVar}.

The response of the service callout will be placed in a custom flow variable called "LatLongResponse". This custom flow variable is created and populated at runtime, just like the custom flow variables "street", "city" and "country".

The response of the service callout looks as follows:

{   "results":[      {         "address_components":[            {               "long_name":"Dietmar-Hopp-Allee",               "short_name":"Dietmar-Hopp-Allee",               "types":[                  "route"               ]            },            {               "long_name":"Walldorf",               "short_name":"Walldorf",               "types":[                  "locality",                  "political"               ]            },            {               "long_name":"Karlsruhe",               "short_name":"KA",               "types":[                  "administrative_area_level_2",                  "political"               ]            },            {               "long_name":"Baden-Württemberg",               "short_name":"BW",               "types":[                  "administrative_area_level_1",                  "political"               ]            },            {               "long_name":"Germany",               "short_name":"DE",               "types":[                  "country",                  "political"               ]            },            {               "long_name":"69190",               "short_name":"69190",               "types":[                  "postal_code"               ]            }         ],         "formatted_address":"Dietmar-Hopp-Allee, 69190 Walldorf, Germany",         "geometry":{            "bounds":{               "northeast":{                  "lat":49.2969047,                  "lng":8.64724               },               "southwest":{                  "lat":49.2911259,                  "lng":8.6389405               }            },            "location":{                 "lat":49.2939276,               "lng":8.6433734            },            "location_type":"GEOMETRIC_CENTER",            "viewport":{               "northeast":{                  "lat":49.2969047,                  "lng":8.64724               },               "southwest":{                  "lat":49.2911259,                  "lng":8.6389405               }            }         },         "place_id":"ChIJ2RBciqS-l0cRNVMdYeMi8jk",         "types":[            "route"         ]      }   ],   "status":"OK"
}

From this response, we only want to keep the "results.geometry.location.lat" and "results.geometry.location.lng" to be added to our response. Therefore, you may have guessed it by now, we will use an "Extract Variable" policy.

4- Read the results of the geocoding service callout

Now that we have the results of the Google geocoding callout available in a "LatLongResponse" flow variable (see previous step), we will extract the "latitude" and "longitude" to be inserted to the response of our API proxy.

To do so, open the Policy Designer by clicking on "Policies" from within your API.

Click on the "Edit" link on the right-bottom corner.

Click on the "BusinessPartnerSet" conditional flow on the left-hand menu of the Policy Designer.

Click on the "+" sign of the "Extract Variables" policy, on the right-handed "Policies" panel.

Name: AssignLatLong

EndpointType and FlowType were set for you when you clicked on the "ProxyEndpoint>PreFlow" link in the previous step

Stream: Outgoing Response

Click on "Add" to add the policy to the flow.

Use the following code to configure the Extract Policy variable:

<!-- Extract content from the request or response messages, including headers, URI paths, JSON/XML payloads, form parameters, and query parameters --><ExtractVariables async="true" continueOnError="false" enabled="true" xmlns='http://www.sap.com/apimgmt'>    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>    <JSONPayload>        <Variable name="lat">            <JSONPath>$.results[0].geometry.location.lat</JSONPath>        </Variable>        <Variable name="long">            <JSONPath>$.results[0].geometry.location.lng</JSONPath>        </Variable>    </JSONPayload>    <Source>LatLongResponse</Source></ExtractVariables>

As you can see from the configuration above, from the root of the JSON, we are reading the first object of the array "results", and point to the "geometry.location.lat" and "lng" attributes. The results of these JSONPath expressions are used to create and populate 2 more flow variables, "lat" and "long".

Note that the source is "LatLongResponse", ie. the flow variable we created previously to store our service callout response.

To check if this worked properly, and possibly debug any issue, you can use the Debugger as mentioned previously.

You will now have a fourth policy in your response pipe:

When you click on it, and scroll down to see the details of the execution, you should see the following:

Note the 2 last fields, "lat" and "long", which represent the flow variables "lat" and "long" that we will now add to the API proxy response.

5- Add the geocoding information to the backend response

The last step of our tutorial, is to mash-up the Google geocoding response with the backend response.

What we would like to end up with, is 2 more attributes in the backend response, within the "address".

For now we have the following:

         "properties":{            "Address":{               "type":"\/IWBEP\/GWSAMPLE_BASIC.CT_Address",               "City":"Walldorf",               "PostalCode":"69190",               "Street":"Dietmar-Hopp-Allee",               "Building":"16",               "Country":"DE",               "AddressType":"02"            },            "BusinessPartnerID":"0100000000",            "CompanyName":"SAP",

And we would like to have the following:

         "properties":{            "Address":{               "type":"\/IWBEP\/GWSAMPLE_BASIC.CT_Address",               "City":"Walldorf",               "PostalCode":"69190",               "Street":"Dietmar-Hopp-Allee",               "Building":"16",               "Country":"DE",               "AddressType":"02",               "Latitude": xxxx,               "Longitude": yyyy            },            "BusinessPartnerID":"0100000000",            "CompanyName":"SAP",

To achieve this, we will use a "JavaScript Policy", that lets us code some specific behaviors that is not available in a pre-configured policy. In our case, because we are using the JSON syntax, the javascript code will be very simple.

The actual javascript code is attached to the API proxy as a "Script".

Therefore, before you add the JavaScript Policy, you will add the corresponding script.

To do so, open the Policy Designer by clicking on "Policies" from within your API.

Click on the "Edit" link on the right-bottom corner.

Click on the "+" sign of the "Scripts" section, on the left-bottom side of the Policy Designer.

Name: addValues

Type: JavaScript

Click on "Add".

Now click on the "addValues" script in the "Scripts" section. The "Script Resource" is being displayed, and you can add the following code that will enhance your backend response with the geocoding information:

var payload = JSON.parse(context.getVariable("response.content"));
payload.entry.content.properties.Address.latitude = context.getVariable("lat");
payload.entry.content.properties.Address.longitude = context.getVariable("long");
context.setVariable("response.content",JSON.stringify(payload));

From the script above, you can see that we are:

- creating a js variable containing the backend response (payload) as JS object

- setting the JSON payload entry "latitude" to the previously generated flow variable "lat"

- setting the JSON payload entry "longitude" to the previously generated flow variable "long"

- setting the response of the API proxy to the payload variable that we just enhanced

Important: please note that we are not working with strings, but with javascript structures, which allows us to simply set and get entries. This is the reason we first parse the response, and in the end stringify it.

Now that the script resource is available, we can reference it through a policy within the response pipeline.

Click on the "BusinessPartnerSet" conditional flow on the left-hand menu of the Policy Designer.

Click on the "+" sign of the "JavaScript" policy, on the right-handed "Policies" panel.

Name: AddValues

EndpointType and FlowType were set for you when you clicked on the "ProxyEndpoint>PreFlow" link in the previous step

Stream: Outgoing Response

Click on "Add" to add the policy to the flow.

Use the following code to configure the Extract Policy variable:

<!-- this policy allows us to execute java script code during execution of an API Proxy --><Javascript async="false" continueOnError="false" enabled="false" timeLimit="200" xmlns='http://www.sap.com/apimgmt'>  <!-- contains the name of the main code file -->  <ResourceURL>jsc://addValues.js</ResourceURL></Javascript>

As you can see, this policy only references the script we have created previously, and will execute it at runtime.

Your proxy should now look like this:

If you test your proxy now, you will see the JSON response containing the latitude and longitude information we requested from Google at runtime.

And here in a more readable format (thanks to https://jsonformatter.curiousconcept.com/):

{   "entry":{      "etag":"W/\"datetime'2016-07-05T21%3A31%3A29.0000000'\"",      "base":"https://SAPES4.SAPDEVCENTER.COM:443/sap/opu/odata/iwbep/GWSAMPLE_BASIC/",      "id":"https://SAPES4.SAPDEVCENTER.COM:443/sap/opu/odata/iwbep/GWSAMPLE_BASIC/BusinessPartnerSet('0100000000')",      "title":{         "type":"text",         "":"BusinessPartnerSet('0100000000')"      },      "updated":"2016-07-06T11:46:37Z",      "category":{         "term":"/IWBEP/GWSAMPLE_BASIC.BusinessPartner",         "scheme":"http://schemas.microsoft.com/ado/2007/08/dataservices/scheme"      },      "link":[         {            "href":"BusinessPartnerSet('0100000000')",            "rel":"edit",            "title":"BusinessPartner"         },         {            "href":"BusinessPartnerSet('0100000000')/ToSalesOrders",            "rel":"http://schemas.microsoft.com/ado/2007/08/dataservices/related/ToSalesOrders",            "type":"application/atom+xml;type=feed",            "title":"ToSalesOrders"         },         {            "href":"BusinessPartnerSet('0100000000')/ToContacts",            "rel":"http://schemas.microsoft.com/ado/2007/08/dataservices/related/ToContacts",            "type":"application/atom+xml;type=feed",            "title":"ToContacts"         },         {            "href":"BusinessPartnerSet('0100000000')/ToProducts",            "rel":"http://schemas.microsoft.com/ado/2007/08/dataservices/related/ToProducts",            "type":"application/atom+xml;type=feed",            "title":"ToProducts"         }      ],      "content":{         "type":"application/xml",         "properties":{            "Address":{               "type":"/IWBEP/GWSAMPLE_BASIC.CT_Address",               "City":"Walldorf",               "PostalCode":"69190",               "Street":"Dietmar-Hopp-Allee",               "Building":"16",               "Country":"DE",               "AddressType":"02",               "latitude":49.2939276,               "longitude":8.6433734            },            "BusinessPartnerID":"0100000000",            "CompanyName":"SAP",            "WebAddress":"http://www.sap.com",            "EmailAddress":"do.not.reply@sap.com",            "PhoneNumber":"0622734567",            "FaxNumber":"0622734004",            "LegalForm":"AG",            "CurrencyCode":"EUR",            "BusinessPartnerRole":"01",            "CreatedAt":"2016-07-05T21:31:29.0000000",            "ChangedAt":"2016-07-05T21:31:29.0000000"         }      }   }
}

Final words

I hope you have enjoyed this tutorial, and that you could get some insights on how powerful SAP API Management can be, once the basic concepts and policies are understood. There is virtually nothing that you can not do in a proxy! In regards to the JavaScript policy, please keep in mind that it's a best practice to always use the pre-configured policies, before writing your own...

Any comments or questions are welcome, and I can provide the final API proxy per mail if needed.

Hi,

I am creating sales order via DI API and trying to set the value for Total Freight Cost (TotalExpns) . Unfortunately I cant seems to find this field is exposed via the API. Is there any way I can set this field a value vis the API?

regards,

Balan Sinniah

Hello all,

I have created an OData Service by exposing the content of Hana MDC Tables, using the XS AS layer.

In the HCP Trial environment, I have created an API Provider pointing to that OData Service.

When creating an API Proxy, the API Management Portal requests an URL to a "Service Catalog" (not mandatory). This is a great feature that automates the creation of resources (ie. conditional flows) in the proxy for instance. However, it looks like "The discover features is currently available for SAP Gateway based services only." (see HCP HANA XS Service and API Management).

My question: is it possible to create a Service Catalog as an XS artifact?

This question relates to an issue I am facing after creating an API Proxy from an API Provider (Type OData, so that I can use the WebIDE to create a SAPUI5 application): I can't create a resource when editing the proxy.

Thanks!

Sven

I've written the start of an RFC server function using the Unicode SAPNWRFC SDK.  It connects and receives data from the SAP ABAP client program successfully so I'm happy there.  The challenge I have is that I want to write the exchanged table content into a local file in a manner very similar to the sample code supplied in the demo folder of the SDK download.

Filehandle = fopenU(fileName, cU(“w”);

fprintfU(Filehandle, cU(“%s”), outputrecord); fclose(Filehandle);

fclose(Filehandle);

The named file is created but contains zero bytes (even when examined with a hex editor there is no unprintable content hidden in there).  But "fclose" function generates a Windows access exception (0xc0000005) and crashes the server.

Obviously it is possible to do this but I cannot see what's wrong with my code at this point - especially since it's a copy of the sample supplied with the SDK.  Can anybody enlighten me please?

Hi Experts,

Now with SAP's roadmap alignining closely with APIs for S/4, C4C, SFSF, ,Ariba etc, how much of % of usage does each customer implementation of this require the usage of APIs?

I was recently part of a mini S/4 implementation where the functional team has not used any APIs.

Please confirm.

Venkat.