Hi all,
In one of my previous blogs, I discussed Apigee, what it is and why is it required? We also discussed the various features and benefits of having Apigee. We saw how to deploy a proxy through the code rather than the Apigee UI deployment feature and many more. So if you like you can go through the basics of Apigee here Getting started with Apigee, just to refresh your knowledge on Apigee-Edge.
Moving forward, we’ll be focusing on some of the policies provided by Apigee. The policies that we’ll be focusing on are :
(1) Extract Variables Policy.
(2) Spike Arrest Policy.
(3) Response Cache Policy.
So before we start with the policies let’s just go through a few basic concepts, in form of question and answers. 🙂 😛
Ques1: What is a Policy in Apigee?
Ans: A policy in Apigee is like a module that implements a specific, limited management function. Policies are designed to let you add common types of management capabilities to an API easily and reliably. Policies provide features like security, rate-limiting, transformation, and mediation capabilities. Apigee Edge enables you to ‘program’ API behavior without writing any code, by using ‘policies’, saving you from having to code and maintain this functionality on your own.
You’re not limited to the set of policy types provided by Apigee Edge. You can also write custom scripts and code (such as JavaScript and Node.js applications), that extend API proxy functionality.
Technically, a policy is an XML-formatted configuration file. Each policy type’s structure is defined by an XML schema.
Ques2: What are the different types of policies provided by Apigee?
Ans: Apigee-Edge policy types are grouped into the following 4 functional categories:
1.Traffic Management
Policies in the traffic management category enable you to control the flow of request and response messages through an API proxy. These policies support both operational- and business-level control. They give you control over raw throughput, and can also control traffic on a per-app basis. Traffic management policy types enable you to enforce quotas, and they also help you to mitigate denial of service attacks.
Example: Spike Arrest Policy.
2.Security
Policies in the security category support authentication, authorization, as well as content-based security.
Example: OAuthV2 Policy.
3.Mediation
Policies in the mediation category enable you to actively manipulate messages as they flow through API proxies. They enable you to transform message formats, from XML to JSON (and vice-versa), or to transform one XML format to another XML format. They also enable you to parse messages, to generate new messages and to change values on outbound messages.
Example: Extract Variables Policy.
4.Extension
Policies in the extension category enable you to tap into the extensibility of API Services to implement custom behavior in the programming language of your choice.
Example: JavaScript Policy.
I hope everyone is now clear about the role of policies in Apigee. Now then let’s move on to their technical details . In case you want to do a hands-on side by side as you go through this blog, you can just clone the project I’ve already setup for your better understanding , here Apigee Playing With Policies Part1
(1) Extract Variable Policy.
As the name suggests, this policy works by extracting the content from a variable, like a source variable containing a request or response messages. The policy applies a text pattern match to the message content and upon a successful match sets the specified variable with the message content being extracted.
After we have extracted the specific message content to our variable, we can reference this variable in other policies as well where we want to leverage the message content stored in the variable.
So just to summarise :
Extract Variable policy extracts information from a request or response and writes it to a specific variable.
Since every policy in Apigee is written in an XML file let’s start looking at the syntax of the ExtractVariable policy:
Syntax:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <ExtractVariables name="Demo-Extract-Variables-Policy"> <DisplayName>DemoExtractVariablesPolicy</DisplayName> <Source>request</Source> <URIPath> <Pattern ignoreCase="true">/a/{extractedVariable}</Pattern> <Pattern ignoreCase="true">/a/{extractedVariable1}/b/{extractedVariable2}</Pattern> <Pattern ignoreCase="true">/a/*/{extractedVariable}</Pattern> <Pattern ignoreCase="true">/a/**/{extractedVariable}</Pattern> </URIPath> <VariablePrefix>myDemo</VariablePrefix> <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables> </ExtractVariables>
Description:
1.) <ExtractVariables name=“Demo-Extract-Variables-Policy”>
Here, Attribute “name” specifies the unique name for our policy if we want to use this policy in some other proxy we need to give the name of the policy specified by the “name” attribute.
2.) <DisplayName> …. </DisplayName>
Should accurately describe the policy’s function to someone who has never worked with that API proxy before.
3.) <Source>request</Source>
The <Source> tag specifies the variable to be parsed. In a request flow, this resolves to the request message. In a response flow, it resolves to the response message. Here we are interested in parsing the request variables hence we will apply the ExtractVariablePolicy in the request flow of the Proxy(don’t worry, the structure is specified in the Code repo).
4.) <URIPath> …. </URIPath>
The <URIPath> tag takes in the Pattern Match operations specified under the <Pattern> tag. Depending on your use case you can have single or multiple Patterns inside the <URIPath> tag so that the incoming proxy.pathsuffix is matched against all the Patterns you have specified.
5.) <VariablePrefix>myDemo</VariablePrefix>
The complete variable name is created by joining the value given in <VariablePrefix> tag, a dot(.), and the name you define in {curly braces} in the <Pattern> element or <Variable> element.
6.) <Pattern> …. </Pattern>
The <Pattern> tag takes in the various Match expressions as per your case. Let’s see them in detail:
- Pattern1
<Pattern ignoreCase=“true”>/a/{extractedVariable}</Pattern>
Here, “myDemo.extractedVariable” is set to whatever appears in the proxy.pathsuffix after “/a/”.
For example, suppose the base path for your API Proxy is /basepath/v1. With an inbound request to http://12ps93r-eval-test.apigee.net/basepath/v1/a/demoValue, the variable “myDemo.extractedVariable” is set to “demoValue”.
- Pattern2
<Pattern ignoreCase=“true”>/a/{extractedVariable1}/b/{extractedVariable2}</Pattern>
We can extract multiple variables too from the request uri, here “myDemo.extractedVariable1“ would be set to the value after “/a” but before “/b” and “myDemo.extractedVariable2” would be set to the value after “/b”. Assuming that we have the same basePath as above ie; /basepath/v1. Then an inbound request to “http://12ps93r-eval-test.apigee.net/basepath/v1/a/demoValue1/b/demovalue2“, will set the “myDemo.extractedVariable1” to “demovalue1” and “myDemo.extractedVariable2″ would be set to “demovalue2”.
- Pattern3
<Pattern ignoreCase=“true”>/a/*/{extractedVariable}</Pattern>
When matching URI paths, we can use the “*” wildcard character in the pattern, where: “*” matches any one segments of the path. So the above pattern would match for any of the following paths (1) “/a/b/demovalue” setting myDemo.extractedVariable to demoValue or (2) “/a/randomPath/demovalue1” that would set myDemo.extractedVaruiable to demoValue1 and etc. But this would fail to match if path is of type “/a/b/c/demoValue” or “/a/demoValue”.
- Pattern4
<Pattern ignoreCase=“true”>/a/**/{extractedVariable}</Pattern>
To overcome the problem in the above pattern we have one more wildCard pattern “**”, where: “**” matches any number of segments of the path and then assigns the myDemo.extractedVariable its value.
For example this will match : (1) “/a/b/c/demoValue” as well as (2) “/a/demoValue” in both the cases myDemo.extractedVariable will be set to “demoValue”.
7.) <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
There may be a case in which none of the patterns match the incoming request ProxyPath, in such a scenario our extractVariablePolicy won’t be able to extract out any information into any dynamic variable which therefore will be remained unassigned.
But now if we try to access this extracted variable in some other policy or proxy it would throw an error when any referenced variable is unresolvable. So to avoid such a scenario we set <IgnoreUnresolvedVariables> to “true“, but if you want to throw an error you can just set <IgnoreUnresolvedVariables> to “false“.
That summarises the use of extract variable policy now let’s move on to the next Policy in line.
(2) Spike Arrest Policy.
The Spike Arrest policy protects against traffic spikes. It throttles the number of requests processed by an API proxy and sent to a backend, protecting against performance lags and downtime.
We can attach Policies anywhere in our proxy’s flow but for Policies like SpikeArrest, it is recommended that you attach this policy in the “request-PreFlow” of the proxy-endpoint so that it can provide spike protection at the immediate entry point of your API proxy.
Your APIs and backend can handle a certain amount of traffic, and the Spike Arrest policy helps you smooth traffic to the general amounts you want.
Let’s have a look at the syntax of the Policy:
Syntax:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <SpikeArrest async="false" continueOnError="false" enabled="true" name="SpikeArrest"> <DisplayName> Spike-Arrest-1 </DisplayName> <Properties/> <Rate>30pm</Rate> </SpikeArrest>
Description:
The main thing to have here is the <Rate> tag that lets you specify the number of requests that your service should acknowledge per minute or per second.
By Default <Rate> is set to acknowledge 30 hits per Minute, we can change it 100pm for acknowledging 100 requests per minute or we can also have 100ps for acknowledging 100 requests per second.
One very interesting thing to note about the Spike Arrest Policy is that when you set the <Rate> to 30pm it doesn’t mean you are allowed to send 30 requests in 1-second or 2-seconds 😛 what it means is that you can hit 30 requests but not more than that in a minute, why so? It’s because when we specified the spike limit to 30pm it gets split into further small spikes ie; “30 requests in 1min” => “30 requests in 60sec” => ” 1 request per 2 seconds”. That is how further spikes were created internally by the policy and hence we can’t hit more than 1 request per 2 seconds. 🙂 Sounds Interesting right 😀
(3) Response Cache Policy
One of the most important policies that Apigee provides is the “Response Cache Policy”, as the name suggests this policy caches the response data from a backend resource for a specified time interval, now then if the same request is made within the specified time period then the cached data is returned back immediately instead of forwarding those requests to the backend everytime.
Clearly, we can verify this by checking the time taken for the response to be sent back to the client. The ResponseCache policy can improve your API’s performance through reduced latency and network traffic. You’ll likely find ResponseCache most useful when backend data used by your API is updated only periodically.
An important point to note here is: The ResponseCache policy type is unique in that it must be attached to both the request and response flow in an API proxy (PreFlow, Flow, or PostFlow).
Syntax:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <ResponseCache async="false" continueOnError="false" enabled="true" name="ResponseCacheCacheHelloMessage"> <DisplayName>ResponseCache.CacheHelloMessage</DisplayName> <CacheKey> <KeyFragment ref="request.uri" type="string"/> </CacheKey> <Scope>Exclusive</Scope> <ExpirySettings> <TimeoutInSec>60</TimeoutInSec> </ExpirySettings> </ResponseCache>
Description:
The first time the API proxy receives a request message for the following URL:
the response is cached coming from the backend. On the second request within 1 minute, a cache lookup occurs — the cached response is returned to the app with no request forwarded to the backend service.
The above Syntax structure allows for caching a value/response in the cache buffer for 60 seconds as specified by the <TimeoutInSec> tag under the <ExpirySettings> tag.
The <CacheKey> element lets us configure a unique pointer to a piece of data stored in the cache. Cache keys are limited to a size of 2KB. Here in our case, we are caching the inbound requests that have the same “request.uri”, as specified in the <KeyFragment> element’s “ref” attribute.
For those of you who are not familiar with the “request.uri” please read this:
Understand the concept `request.uri` for Responses and Requests.
That covers the 3rd and the last Policy for this blog, I’ll be covering other important Policies in my upcoming blog: “APIGEE-EDGE: Playing With The Policies(Part2)”.
For a better understanding of the Policies, you studied in this blog, you should clone my project and analyze the proxy and policies from there. I have implemented the above-mentioned policies here:
Playing with the Policies in Apigee – Part1
I hope you like the content, in case you have any doubts please feel free to comment on the post or get in touch with me, or if you want to suggest something to me on the topic please be my guest and let me know, let’s share the knowledge we all have. 🙂
Thanks and happy learning 🙂 🙂 .
2 thoughts on “APIGEE-EDGE: Playing With The Policies(Part1).11 min read”
Comments are closed.