PAPI also provides these additional features:

• Use Search properties as a quick way to identify currently active property versions.

• 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.

• To control which rule format is assigned to a property, see Freeze a rule tree's feature set and Update rules to a newer set of features, both of which are based on the operations that read and write rule trees. See Update client settings to set the default rule format for new properties.

• 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.

Freeze a feature set for a rule tree

This section describes a specific use for the Update a rule tree operation: to assign a specific rule format's feature set to a rule tree. See also Freeze a rule tree's feature set to increment the versioned set of rule format features that are assigned to a rule tree.

As best practice, assign the most recent dated rule format in any API driven workflow. Otherwise, if you assign the latest rule format to your rule tree, features update automatically to their most recent version. This may abruptly result in errors if JSON objects your rules specify no longer comply with the most recent feature's set of requirements.

PAPI tracks rule formats in a database keyed by rule format version date strings. These reference rule format schema objects, which specify the full set of behaviors and criteria available for a given product and the set of modules it may enable, as well as their allowed options and option values.

New properties' rule trees are assigned whatever rule format you specify as a default client setting, or else the most recent dated rule format version available. To confirm your rule tree is already frozen, and freeze it if necessary:

1. Run Get a rule tree and store the URL you use to get it.

2. If the rule tree's top-level ruleFormat member is a dated version, the rule tree is already frozen. Continue to freeze it only if it's latest.

3. Run List rule formats and store the most recent dated rule format version string.

4. Build a custom MIME type string using this template, application/vnd.akamai.papirules.vYYYY-MM-DD+json, where vYYYY-MM-DD is the variable rule format version string.

5. PUT the rule tree to the same URL you used to get it, adding the custom MIME type to the request as a Content-Type header.

See also Get a rule tree for steps to update a rule tree to a more recent rule format. If the set of features you include in your rule tree doesn't conform to the associated rule format schema, the response includes errors that may prevent you from activating the property.

Update rules to a newer set of features

This section describes a specific use for the Get a property rule tree operation. You can update the versioned set of rule format features that are assigned to a rule tree. See also Freeze a rule tree's feature set to assign a specific rule format.

📘

As best practice, don't update to the latest rule format in PAPI for better stability.

Use this procedure to update the set of features assigned to your rule format. This also modifies the rule tree to implement most required syntax changes, such as changes to option names and enum values. You can't use this approach to assign an older rule format. 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.

1. List rule formats and store a more recent ruleFormat version to which you want to update the rule tree.

2. Build a custom MIME type string using this template, application/vnd.akamai.papirules.vYYYY-MM-DD+json, where vYYYY-MM-DD is the variable ruleFormat version.

3. GET the rule tree as described above, adding an Accept header that specifies the custom MIME type.

4. Confirm the response object's top-level ruleFormat reflects the desired version.

5. PUT the converted rule tree to the same URL you got it from, adding a Content-Type header that specifies the same custom MIME type.

This represents the formal update path to increment versions of deployed features. Do not assign a rule format of latest, as that doesn't modify your rule tree to smoothly upgrade to any emerging changes to features. The latest rule format is instead likely to produce unexpected errors over time.

Updating to a more recent rule format modifies the rule tree to accommodate renamed options, renamed enumeration values, and two-state enums retyped as boolean. Other values may not be able to convert, such as string numerics retyped as actual numerics, or if an updated behavior features a new required option or different validation criteria. If this occurs, the PUT response's rule tree object includes errors that help you refine the updated rule tree, as detailed in the Errors section.