Part 6 - Overview of API Proxy Policies

[former_member181883]

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:

Property Name	Property Value
Name	SAPDevSystemES4
Description	ES4 Developer Center
Host	sapes4.sapdevcenter.com
Port	443
Path Prefix	/sap/opu/odata/
Use SSL	True
Authentication Type	Basic
User Name	<your ES4 userid>
Password	<your ES4 password>
Service Collection URL	/iwfnd/catalogservice/ServiceCollection

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