Fast validation, activation, and fallback

PAPI's most important function is to modify rule trees assigned to sets of hostnames, and to activate them on Akamai's networks of edge servers. As described in the Rule Trees section, rule trees are potentially very large, complex objects that often require frequent, iterative optimizations. See how you can accelerate and simplify the rule tree development.

Skip validation while editing

Under PAPI's traditional development cycle, each time you modify and save a rule tree, you'd need to wait for a lengthy set of validation tests to complete, making an iterative development cycle more difficult. The current API release provides shortcuts to accelerate development. One option allows you to defer validation until you're ready:

Both the rule tree and the set of hostnames are part of the same property definition, for which there's a single validation process. The benefits of routinely deferring validation increases along with the size of the rule tree, and with the number of hostnames you assign it to. When you defer validation, the response object comes to you more quickly, and without its usual errors and warnings arrays described in the Rule tree errors and warnings section.

🚧

You'd still need to fix any errors, and to either fix or acknowledge any warnings to proceed with the activation. To get this information, enable validation again before activating the property.

Perform FAST or dryRun validation

When running the Update a rule tree operation, instead of skipping a validation, you can accelerate it, or run the operation simply to gather errors rather than modify the rule tree. For both scenarios, set the validateRules query parameter to the default true value and:

  • Setting the validateMode query parameter to FAST performs a more superficial JSON syntax check. This focuses on the errors that are more likely during frequent iteration. It skips a lengthier set of execution tests on the converted XML metadata.

  • Alternately, setting the dryRun query parameter to true performs the full validation check, but without saving the rule tree. The response provides any resulting errors and warnings, without committing changes to the rule tree. You can only specify dryRun with validateMode set to the default FULL validation.

Before activating a revised rule tree, you need to fix any errors from a full validation. As part of the activation, you either set the acknowledgeAllWarnings flag or pass in an array of acknowledgeWarnings warning IDs. Activation is much faster if the property's set of hostnames doesn't change.

Revert an activation

You may also have the option to quickly revert an activation:

  • If you detect a problem with the rule tree within an hour of its activation, POST another activation with useFastFallback set to true. Within a few seconds, it disables the current activation and falls back to the previous version. Fallback may also occur automatically if the activated metadata fails various execution tests on edge servers. The fallback option isn't available if you've changed the set of property hostnames, or if this is the property's first activation. When polling the activation's status, the canFastFallback flag indicates whether fallback is possible.

  • If the fast fallback option isn't available as indicated by "canFastFallback":false, you need to separately activate the previous version of the rule tree known not to cause problems.

🚧

Contact your Akamai representative for guidance on expected latency, both to validate your property's rule tree and to activate it worldwide.