Rule trees

A property's main functionality is encapsulated in its set of rules that let you decide how to respond to different kinds of requests. Here we detail how rules operate, how to configure prerequisite features, and how to structure the rest of a rule tree from the root down. It also shows how to deal with special read-only features, and to interpret contextual rule format JSON schemas that specify your product's level of support for various behaviors and criteria.

Though you set the rules in JSON, once activated, the property settings are distributed to the ​​Akamai​​ network as XML metadata. This low-level XML format combines information about the property's rules and hostnames.

The default rule and children rules

Every rule tree opens with a top-level rules element that specifies a mandatory default rule object. If you want to further adjust how your content is served over the edge network, you can add a children array of nested rule objects, where you specify individual behaviors and optional criteria. PAPI supports a catalog of writable behaviors and criteria with templated values that offer guide rails for easier implementation. However, if you need additional dedicated settings that regular behaviors can't express, an ​Akamai​ representative can build a custom feature in XML for you.

Rule trees logic

Overall, the principles governing how rules work are very simple.

  • Rules are evaluated from top to bottom.
  • A rule first evaluates its criteria, then, if the set of criteria matches, executes its behaviors and nested children.
  • If any behavior is specified more than once within a set of executing rules, the last one overrides those that precede it.
  • In some cases the ordering of different behaviors that perform similar functions may also matter.
  • In other cases you can re-use the same behavior to do different things that don't conflict with each other, for example, by modifying one HTTP header and then a different one.

Once you've completed work on your rule tree, a PUT request with the revised data saves it:

PUT /papi/v1/properties/prp_175780/versions/3/rules/?contractId=ctr_1-1TJZH5&groupId=grp_15225

If the API detects any problems with the data, they're noted as part of the response, and you may need to either fix or acknowledge them before you activate the property with that rule tree. See the Activate a property operation. For details on the range of problems you may encounter when modifying a rule tree, see the Errors section.