Meta Data

Advanced Metadata: A Brief Overview

April 28, 2017 by Jay Sikkeland

Akamai products offer a broad set of features to let you control how edge servers process your traffic. Property Manager/PAPI features are organized as nested rules, and most of the time, these built-in features are all you need. Especially now with support for variables, you can design very complex functionality.

But sometimes you need more; enter Advanced Metadata.

What is Metadata?

The term metadata usually refers to high-level information about some other set of data. At Akamai, Metadata refers to the XML-based programming language that configures our Edge Servers. For example, here's an XML snippet that matches on a .jpg file extension, enables caching, and sets the cache TTL to 1 hour:


<match:uri.ext case="off" result="true" value="jpg"> <cache:no-store>off</cache:no-store> <cache:max-age>1h</cache:max-age> </match:uri.ext>


Everything you configure and activate in Property Manager (or PAPI) gets translated to metadata and pushed to Akamai’s edge servers, where it executes. Metadata can do almost anything, good and bad, which is why WRITE access to metadata is restricted, and only Akamai employees can add metadata to a property configuration directly. But as you'll see below, you have some options to implement customized Advanced Metadata, and even more in the future.


The Property Manager API (PAPI) operates on an intermediate format known as PAPI JSON, which is converted to XML metadata when uploading or saving a configuration. The PAPI JSON format is structured as rules, containing matches (if-statements) and behaviors (operations to perform). Here’s an example of a PAPI JSON rule with a match on file extension .jpg and caching behavior to set the TTL to 1 hour.


{     "name": "Cache jpg for 1 hour",     "criteria": [         {             "name": " fileExtension ",             "options": {                 "matchOperator": "IS_ONE_OF",                 "values": ["jpg"],                 "matchCaseSensitive": false             }         }     ],     "behaviors": [         {             "name" : "caching",             "options" : {             "mustRevalidate" : false,             "behavior" : "MAX_AGE",             "ttl" : "60s"         }     ] }


Three Types of Advanced Metadata

Advanced, customized metadata can appear directly in three different places in Property Manager and PAPI:

  • Advanced behaviors - Behaviors that can be part of any rule.
  • Advanced matches - Use when standard match criteria don't meet your needs.
  • Advanced override rule - The final rule that executes.

As mentioned earlier, you need to get your Akamai account team to add the advanced metadata to your Property Manager config.

Advanced Behaviors

Advanced behaviors are used just like other behaviors, except they contain metadata XML and display with a lock icon, meaning they can't be altered. Here's an advanced behavior as it appears in the Property Manager.

And here is the resulting advanced behavior expressed in PAPI JSON, including the enclosing rule.


{       "name" : "Advanced Behavior",       "uuid" : "f028f77e-18ef-4162-94b9-84a42e58b7c1",       "behaviors" : [ {         "name" : "advanced",         "options" : {           "description" : "Add the string \"foo\" to the custom log field",           "xml" : "<reporting:lds.custom-field>foo</reporting:lds.custom-field>"         },         "uuid" : "3aa5edaa-2f48-4383-9ee7-38be4f9c9b23" }


Advanced Matches

Advanced matches are used as criteria for a rule when the standard match criteria don't meet your needs. Commonly used for matching on regular expressions, metadata stage, request type and request method.

Here is an example of an advanced match with regex in the Property Manager UI.

And below is the resulting matchAdvanced criteria in PAPI JSON. Note the open XML field that contains the metadata XML to insert before the behaviors, and the closeXml field with the metadata XML to insert after the behaviors. The closeXml needs to close the corresponding openXml tag; otherwise, you'll get an error when uploading the JSON.


{ "name" : "Advanced Caching Rule", "comments" : "Set 1 hour TTL for certain files", "uuid" : "fc16410d-b776-49af-b7a8-2759a8c01bfb", "criteriaMustSatisfy" : "all", "criteria" : [ { "name" : "matchAdvanced", "options" : { "description" : "advanced match on file names starting with \"foo\" plus a number", "openXml" : "<match:regex string=\"%(AK_FILENAME)\" regex=\"^foo[0-9]\">", "closeXml" : "</match:regex>" }, "uuid" : "4bfc884c-62f7-4de4-acc4-c6f3d6d940e3" } ], "behaviors" : [ { "name" : "caching", "options" : { "behavior" : "MAX_AGE", "mustRevalidate" : false, "ttl" : "1h" }, "uuid" : "87b2994a-9317-401f-919d-c184c84219e7" } ], "children" : [ ] }


Advanced Override Rule

You usually use advanced matches as criteria for a rule when the standard match criteria don't meet your needs, typically to match on regular expressions, metadata stage, request type, and request method.

Here is an example of an advanced match using a regular expression within the Property Manager.

The resulting PAPI JSON is a single entry called advancedOverride. When the Metadata XML generates, this line is inserted at the very end of the configuration.


    "variables" : [ ],     "advancedOverride" : "<reporting:lds.custom-field>foo</reporting:lds.custom-field>"   },   "warnings" : [ {


Use the UUID

Notice the uuid value in the PAPI JSON examples above? Normally, the uuid is optional, but for any rules, behaviors, and matches containing metadata, the uuid ensures that the metadata has not been altered.

When the metadata is first added to the configuration, we generate an MD5 hash of the content, which becomes the uuid value. For subsequent updates to the configuration, we compare the uuid of any rule (including all parent rules), behavior, and match containing metadata against the previous version of the configuration to make sure it hasn't been altered.

So, if your configuration contains metadata, and you use PAPI to upload a new version, make sure you don’t alter the metadata in any way (even an extra space causes a validation failure) and don't change the uuid for the related rules (including all parent rules), advanced behaviors, and advanced matches.

Improvements On the Way

We realize that the restrictions around metadata make it harder to automate configuration management. We have some significant improvements coming shortly in this area. Custom Behaviors, Custom Override Rules. Cloning enhancements will allow you to copy behaviors and rules that contain metadata among configurations, and to clone all the content (including any metadata) from one configuration to another. Stay tuned for updates.

Jay Sikkeland is a Senior Product Manager at Akamai Technologies.