API
TrainingSupportCommunity

Dynamic rule updates

Akamai often modifies the catalog of behaviors and criteria, each time deploying a new internal version of the feature. To allow new features to roll out without incrementing the core API’s version, PAPI supports a system of versioned objects called rule formats. PAPI versions schema objects as a whole and creates dated snapshots for the set of features available within a property's rule tree. The latest rule format contains the highest version of each behavior and criteria, so that you can take advantage of the fresh improvements and new features that get released on a regular basis.

Understand rule format schemas

PAPI provides rule format schema objects that define the features you may enable under a product. This section shows how to interpret a rule format and use it to validate a rule tree or research available features.

The schema's relevant content is nested within the outer object's definitions member, which is empty in this example:

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "type": "object",
    "properties": {
        "rules": {
            "$ref": "#/definitions/toprule"
        }
    },
    "required": [ "rules" ],
    "definitions": {
    }
}

The top level of the schema specifies only that the rule tree must feature a rules member, specified indirectly within a large definitions section that this example doesn't display. The toprule itself specifies an object, which needs a name. While these specify the object's basic structure, the definition's catalog member contains available features, separately within the behaviors and criteria sub-trees. Each of those object's keys list supported features, and the values define their components.

📘

The features specified in the rule format represent all the behaviors and criteria the product supports, not necessarily those currently enabled for your account. Each product specifies a baseline set, with other more specialized features enabled with add-on modules, as discussed in key concepts and terms. To determine the set of features currently available on your account, saving a property that specifies them returns an error that notifies you otherwise.

This example shows a typical behavior definition for caching, along with its component options, some of whose data types are referenced elsewhere within the schema.

"caching": {
    "type": "object",
    "properties": {
        "name": {
            "enum": [ "caching" ]
        },
        "uuid": {
            "type": "string"
        },
        "options": {
            "type": "object",
            "properties": {
                "behavior": {
                    "default": "max-age",
                    "enum": [ "max-age", "no-store", "bypass-cache", "both", "cc", "expires" ]
                },
                "mustRevalidate": {
                    "default": "off",
                    "enum": [ "off", "on" ]
                },
                "ttl": {
                    "$ref": "#/definitions/catalog/option_types/duration"
                },
                "defaultTtl": {
                    "$ref": "#/definitions/catalog/option_types/duration"
                }
            }
        }
    }
}

Understand the limitations of the rule format's available data. While each option's basic data type is specified, additional validation logic isn't necessarily available within the schema, and may be implemented as part of the API's back end. The rule format also doesn't represent dependencies among the options. For example, many behaviors feature a high-level enabled switch. When disabled, the API typically ignores any other specified option. When enabled, there may be other contextual dependencies among the options. The behavior and criteria reference references detail most of these dependencies.

Rule formats often specify only minimal validation criteria. For example, the rule format's option_types section describes custom data formats, such as this example representing a CP code object with a required id member:

"cpCode": {
    "type": "object",
    "properties": {
        "id": {
            "type": "number"
        }
    },
    "required": [ "id" ]
},

The rule format doesn't specify the name member that also typically appears within a cpcode object. It doesn't specify what happens if you omit the name, or supply other members unknown to the API's back end. The back end may behave slightly differently over time, even if you freeze the API's set of features.

Check the following links for more information related to rule formats:

  • If you want more details about the underlying features that are applied as part of a property's rule tree, run List rule formats to get available versions for each feature set, and Get a rule format's schema to validate a rule tree against a specific rule format's supported features.

  • If you want to apply a common set of customized XML metadata to more than one property, see the Custom behaviors and Custom overrides interfaces.

Use the latest rule format

Under PAPI’s original design, you had to choose between a dated rule format that was stable over time, but didn’t include newer features or bug fixes, or the format that changed with every catalog release, but posed a serious risk of breaking down your configuration.

Now PAPI uses the dynamic rule updates feature, where every update to Property Manager Catalog is backwards compatible. With the updateRules query parameter defaulting to true in PUT or PATCH operations to update your rules, you can continuously use the latest rule format and keep working with your current rule tree without causing new validation errors as ​Akamai​ dynamically modifies catalog options. Review how PAPI handles different types of feature updates in this new approach:

  • New additions. Whenever Akamai adds a new feature or introduces a new option in an existing behavior or match, it’s automatically filled with default values. Once you decide to take advantage of these new capabilities, you can explicitly set and override the default values.
  • Removals. You don’t need to update your rule tree when Akamai removes a feature or option you’re currently using from the catalog. When you call PUT or PATCH to update your rules, PAPI ignores these values if you pass them in the request body.
  • Renamed options. You don’t need to update your rule tree when Akamai renames a feature or option you’re currently using. When you call PUT or PATCH to update your rules, PAPI automatically recognizes the old name and further processes it under a new one.

With your rule format set to latest, PAPI performs the upgrade functions in the catalog each time you run the Update a property’s rule tree operation. If applicable, on Get a property's rule tree, PAPI adds new fields with default values, and removes or renames options. As these updates may trigger new warnings, they won't cause any new activation-blocking errors. Some pre-existing errors might get resolved automatically as a result of the catalog upgrade. See Upgrade from a frozen rule format to latest for step by step instructions on how to convert from older JSON rule tree inputs.

📘

The originalInput query parameter in PATCH and GET operations suppresses any updates from showing in your rule trees.

  • The parameter defaults to true, which means PAPI still upgrades catalog features in the background each time you run these operations, but the response yields the rule tree just as you last saved it.
  • When you set it tofalse, PAPI includes latest rule changes in your original input, such as new options with default values.

Upgrade from a frozen rule format to latest

If you’re currently using a frozen dated rule format, but wish to take advantage of the new or updated features ​Akamai​ releases routinely, upgrade your properties to the latest rule format. This is a one-time procedure that updates the set of features to their highest versions. In this procedure, the initial GET operation specifies a MIME type that converts the rule tree, after which you PUT the converted object to write it back.

❗️

If you’re using includes with your properties, you should continue working with frozen rule formats. The latest rule format is not supported, as includes and the parent properties that reference them must use the same set of features. See Rule format schemas for more details.

  1. Get a property's rule tree, adding an Accept header that specifies the MIME type for the latest rule format:
    Accept: application/vnd.akamai.papirules.latest+json
  2. Confirm the response object's top-level ruleFormat reflects the latest version.
  3. PUT the converted rule tree to the same URL you got it from, adding a Content-Type header that specifies the same MIME type:
    Content-Type: application/vnd.akamai.papirules.latest+json

Updating to the latest rule format applies new fields with default values, and removes or renames feature options.

Versions older than v2020-03-04 may not be able to seamlessly convert to the latest rule format. If this occurs, the PUT response's rule tree object includes errors that help you refine the updated rule tree, as detailed in the Rule tree errors and warnings section. Once you solve all the errors and convert to the latest rule format, PAPI will automatically upgrade your set of catalog options to the newest available version.

Use the latest behaviors and criteria by default

When you decide to take advantage of the most recent updates to behaviors and criteria, you can set latest as a default rule format and routinely exchange data as plain application/json, instead of specifying this content type each time you exchange rule trees:

Accept: application/vnd.akamai.papirules.latest+json
Content-Type: application/vnd.akamai.papirules.latest+json

New PAPI users have ruleFormat: latest enabled automatically. Otherwise, you can set the default value manually in your client:

  1. Run the Get client settings operation.
  2. Change the ruleFormat to latest.
  3. Use the modified object to run the Update client settings operation.

Thereafter, any time you exchange rule format data, specifying application/json sets the rule format version to latest, where modified rules update dynamically.