HowTo: Akamai CDN integration

3scale actively supports Akamai with ESI (Edge Side Includes) scripts. This HowTo gives an overview on the integration with 3scale using these ESI.

Prerequisites

Before you start these steps, you have to assure you have your Akamai set up with the Edgesuite enabled. Also Akamai does not have ESI processing, which is required for the integration, enabled in all their installations, it depends on the type of contract/volume that you have. Typically this is something that you have to request from your Akamai representative.

The guide

Following are some details of how the integration with Akamai is implemented.

The key to extract the first level string on the path to pass it as a method to the 3scale backend. An example of an ESI that does this with a regular expression is:

<esi:try><esi:attempt><esi:choose><esi:when test="$(REQUEST_PATH)
matches '''^/(.*?)/'''">
<esi:include src="http://su1.3scale.net/transactions/authrep.xml?usage[$(MATCHES{1})]=1&usage[hits]=1&no_body=true
&provider_key=YOU_PROVIDER_KEY&app_key=$(QUERY_STRING{app_key})&app_id=$(QUERY_STRING{app_id})"
ttl="0"/>
<esi:include ttl="600"
src="http://your_origin_server.com$(REQUEST_PATH)"/>$add_header('Content-Type',
'application/xml')
</esi:when></esi:choose></esi:attempt><esi:except>Access
denied</esi:except></esi:try>

Describing it in a more detail the fragment below:

<esi:include src="http://su1.3scale.net/transactions/authrep.xml?usage[$(MATCHES{1})]=1&usage[hits]=1&no_body=true
&provider_key=YOU_PROVIDER_KEY&app_key=$(QUERY_STRING{app_key})&app_id=$(QUERY_STRING{app_id})"
ttl="0"/>
is where you build the request to 3scale backend. These can be fixed strings, or it can include the matches of a regular expression on the original requester URL. E.g.:
<esi:when test="$(REQUEST_PATH) matches '''^/(.*?)/'''">

The ESI allows you to get query string paramterers from the original requester URL without having to do regular expresions like:

QUERY_STRING{app_key})
This gets the value of the parameter app_key on the query_string (&app_key=foo&).

Obviously, you can construct an arbitrarily complex ESI to map the original requests from end-customers to the methods that you want to track. As long as you can derive those methods from a regexp from the URL the procedure is quite simple.

The ESI script is evaluated by the Akamai edge servers upon any request from the end-customers. The evaluation consists of building the URL that will hit the 3scale backend and if the return is a 200 it will proceed on the normal flow, either serve it from the edge cache or fetch it from the origin (your API). If the 3scale backend returns a non-200, Akamai will not serve the request and default to a customer error page:

<esi:except>Access denied</esi:except>
In this case it's a simple string, but it can also be a static page.

We recommend you start by reporting just hits, no regexps involved, and then build the rest of methods when you have tested it. Once the ESI is ready you can set it up on your Akamai control panel if you have the Edgesuite packet enabled.