Validation best practices

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. 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. To accelerate development, you can use shortcuts to defer validation until you're ready:

• When running the Update a rule tree operation, set the validateRules query parameter to false.

• When running the Update a property's hostnames operation, set the validateHostnames query parameter to false.

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:

• Set the validateMode query parameter to FAST to perform 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, set the dryRun query parameter to true to perform 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.

Use case: set up a rule for your custom site

Based on the newly added custom hostname discussed in Create a new edge hostname, you'd typically add a corresponding set of rules. Appending this simple example to the rule's array of children as part of a PUT request tests the hostname and assigns a different CP code to report on and separately bill for the custom site's traffic.

{
    "name": "Custom Site",
    "criteria": [
        {
            "name": "hostname",
            "options": {
                "matchOperator": "IS_ONE_OF",
                "values": [ "custom.example.com" ]
            }
        }
    ],
    "behaviors": [
        {
            "name": "cpCode",
            "options": {
                "value": {
                    "id": 54321,
                    "name": "custom site"
                }
            }
        }
    ]
}

👍

While the hostname criteria matches hostnames, the clientIp criteria matches IP addresses.