Now that SAP API Management is available on HCP Trial we already can see quite a lot of people using it, which is good.
So far we have covered topics like Policy handling, URL masking and much more content is on its way. You can always refer back to this living document SAP API Management - Overview & Getting started in order to keep up to date on what is available.
This blog will serve as a companion to the Policy handling blog mentioned above, as an explanation of how an API Proxy runs through policies, and how to decide where a policy will therefore live in that "Flow". For explanation about what a policy is or what it does, please refer to the blogs specifically written to explain that.
TOC
How Do Policies Work in an API Proxy?
When a policy is added to an API Proxy, it is added to a specific point in the data stream, thus providing highly granular control. This is broken down into 2 "Endpoints":
- API Proxy Endpoint
- Incoming request – Requests from external source (User application, B2B resource, etc.) to the API Proxy residing on SAP API Management
- Outgoing response – Data request sent from API Proxy residing on SAP API Management to original request source.
- Target Endpoint
- Incoming request – Requests from API Proxy on SAP API management to Target Endpoint
- Outgoing response – Data response from Target endpoint to API Proxy on SAP API management, in response to request received from API Proxy.
There are certain classes of policies which are best applied to the API Proxy Endpoint, like Authentication, Data Throttling, Threat Protection, as these will be handled by API Management before any routing to the backend has been initiated. Additionally Statistics and Analytic collections should be done on the API Proxy Endpoint (response) to gather data only after the entire process has been completed. Policies that deal with specific routing should be placed on the Target Endpoint to trigger only after the destination has been determined. Some policies can be applied in either segment, and are determined by the use case.
After determining the appropriate Endpoint placement for a policy, and whether it should execute in the request or response, the next step is selection of the subdivision of flow, which defines in what order policies are executed. Each request and response path in a proxy endpoint and target endpoint is broken down into the following flows:
- Pre-Flow
- Always executes before any other flows.
- The policies defined in the pre-Flow are applied to every message that passes through an endpoint.
- Conditional Flows
- Execute only when a conditional statement defined for the Flow evaluates to true. These conditions tell the Proxy, “if you see this, then do that.”
- An endpoint can define any number of Conditional Flows, but only the first Conditional Flow whose condition evaluates to true executes. That means the policies attached to the Conditional Flow only execute when the Conditional Flow executes.
- Post-Flow
- Always executes after all other Flows.
- Like Pre-Flow, the policies defined in the Post-Flow are applied to every message.
- (OPTIONAL – only for certain policies)
- PostClient-Flow
- § Executes after entire flow, including response to the Client has been completed.
- § Only used by certain logging policies to track various metrics about API Proxy usage.
- PostClient-Flow
How to Visualize API Proxy Flow
At first this sounds complex, but after working with policies for a little bit, it becomes second nature, and becomes a powerful tool to controlling interactions. There are many ways to visualize this, but I like to think of it as 4 quadrants, each of which allow controls on data behavior.
The Client initiates a request, which connects to the API Proxy endpoint (Incoming Request), following PreFlow, Conditional Flow, PostFlow, and then traverses the diagram to the right, hitting the Target Service, which is then processed, and returned to the Target Endpoint (Outgoing Response), traversing to the left until it is returned to the Client. A policy could be placed in any of the 12 Flow points.
How To Actually Do It
Inside of the API Management Portal this is all managed in the Policy Designer page:
By selecting the appropriate flow (shown in boxes above), then choosing incoming request or outgoing response, a policy is placed at the right point in the API Proxy flow. One thing to note is that when multiple policies are placed in the same flow area, they are processed sequentially, in the same order as shown in the first diagram (Left to Right for requests, Right to Left for responses).
Some people say, that's great theory and all, but I would like an example, so here is a simple (and lightly contrived) example of flow in action.
Flow Example
A high level example of what this could look like in action – We have an example API proxy called “SalesOrder” which exposes an OData resource, from an EPM backend, as a single part of a Sales Order process. More specifically let’s look at the flow for reading a specific OData resource called “Products” which returns a list of available Products.
Client Request calls the API-Proxy, specifying the Products resource. This triggers the following sequence:
1) Proxy Endpoint Incoming Request
- Pre Flow Policies triggered
- Verify API Key – Checks URI request for valid APIKey to ensure that Client has permissions to access this API
- Conditional Policies triggered for resource “Products”
- Default - Checks that user request has permissions to perform “GET” operation on Products
- Quota – Checks that resource requests are not overloading backend system
- Post Flow Policies
- Assign Message - Strip out the API Key from the URI to be passed to the backend, both for security and because this would not be understood by the backend system.
- Response Cache – Check for cached data, if request was made recently, return Cached data from SAP API Management instead of going to BackEnd.
2) Target Endpoint Incoming Request
- Pre Flow Policies triggered
- JSON to XML – Prior to passing request to backend, convert JSON request to XML, so that Backend can understand data.
3) Target Endpoint Outgoing Response
- Post Flow Policies triggered
- Response Cache – Pull response data into Cache within API Management, so that if another request is made in defined period, Cached data can be returned from SAP API Management.
4) Proxy Endpoint Outgoing Response
- Pre Flow Policies triggered
- XML to JSON – After response received from Backend, per form conversion of XML response back to JSON format, for efficient transport, and to meet expectation for client.
- PostClient Flow Policies triggered
- Statistics Collector – After API Proxy has run in its entirety, collect information about full end to end response times to track API Proxy performance. This is separate from standard Analytics which are collected by default on every API call.
We see here then the flow that our API Proxy processes, as well as some simple examples of Policies living in Pre-Flow, Conditional Flow, and Post-Flow. Depending on the specific need, some of these policies could have been placed in a different part of the flow cycle, the API Proxy and Policy design provides for a great deal of flexibility and control over what happens in a request made to a backend resource.
Final Thoughts
This Products Request example could also have many more Policies depending on need, for example, if the product listing were part of a catalog which only was exposed to employees, there might be an OAuth verification Policy. If the Proxy needed to provide a CSRF security token, there might be a Service Callout policy to make a Fetch token request to the backend, followed by an Extract Variable policy to get the Token response value, and an Assign Message Policy to add that Token value to the message Header being sent to the Backend, and more. Hopefully this example explains the basics of flow however.
Please continue to check back for more informational content surrounding SAP API Management !
For questions, feedback, concerns, feel free to leave a comment, or send us an E-Mail.
- SAP Managed Tags:
2 Comments
