Learn more:

• Property Manager

• PAPI Feature Catalog Reference

• PAPI Feature Catalog Reference, v2018–02–27

Overview

NOTE: This initial API version 0 has been superseded. See version 1 for the latest features. Upgrade to the new version of the API at your earliest opportunity, mainly by updating to v1 in all request URLs. Version 1 is backwards compatible with v0, so your code will work as before, but you need to upgrade to v1 to take advantage of many upcoming features. A deprecation notice for PAPI v0 will be posted in early July, 2017. The v0 endpoints will continue to work until January, 2018. This v0 API guide has been frozen, so consult the v1 guide for the most up-to-date information.

The Property Manager API (a.k.a. PAPI) offers a programmatic interface to manage how Akamai edge servers process requests, responses, and objects served over the Akamai platform. A distributed property configuration encapsulates all the rules for how to process end-user requests for your web assets. Like Akamai Control Center’s Property Manager, this API lets you modify your property configurations and activate them on Akamai staging or production networks. The API allows you to access the same features rapidly and flexibly using your own tools. PAPI allows you to generate properties dynamically, associate them with dynamically generated hostnames, and to create new CP codes to report on your content’s traffic.

Getting started

Before using PAPI for the first time:

• Contact your Akamai representative to enable it for your account.

• Review Get Started on available tools. Note that tools such as edgegrid-curl and edgegrid-python assume a maximum message-body size of 2048 bytes, which for PAPI needs to increase to 128K. How you do so depends on your chosen tool, for example by setting max-body:131072 in the .egcurl file, or in python by passing in max_body:131072 as part of the EdgeGridAuth() call.

• Review Authorize Your Client to create your API access credentials and authorizations, making sure you enable read/write access for the Property Manager API grant. When setting up your credentials for use with PAPI, make sure to associate it with a user who does not have access to more than one portal account, as that can cause authorization errors.

• Review the API’s Known Issues.

• Get help from the Akamai developer community and provide feedback. You can also contact your Akamai representative for support. We want to hear from you!

The security token you use to form a custom domain for the request, as discussed in The API Identity Model, keys to your account. The entire URL for the GET request will look something like this:

https://akzz-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX.luna.akamaiapis.net/papi/v0/contracts/

Once you have a custom domain that is keyed to your account, you can gather other prerequisite data from the API: the relevant contract and group to access other PAPI objects, and a product to create new ones. See the Resources section for PAPI’s full range of capabilities.

PAPI concepts

This section provides a road map of all the conceptual objects you deal with when interacting with PAPI, and provides pointers to where you can learn more.

• Accounts: Akamai customers access all their services via an account key. While administrators may have access to more than one account, in general they provision all their web assets under a single account within Control Center. PAPI responses often return details about the account to which the security token you use to access the API is implicitly tied.

• Groups: Each account features a hierarchy of groups, which control access to properties and help consolidate reporting functions, typically mapping to an organizational hierarchy. Using either Control Center or the User Admin API, account administrators can assign properties to specific groups, each with its own set of users and accompanying roles. Your access to any given property depends on the role set for you in its group. Along with information about the contract, you need the group identifier to access virtually all of PAPI’s resources. (See the Groups interface and Group object type.)

• Contracts: Each account features one or more contracts, each of which has a fixed term of service during which specified Akamai products and modules are active. Along with information about the group, you need the contract identifier to access virtually all of PAPI’s resources. (See the Contracts interface and Contract object type.)

• Products: Each contract enables one or more products, each of which allows you to deploy web properties on the Akamai edge network and receive associated support from Akamai Professional Services. Products allow you to create new properties, CP codes, and edge hostnames. They also determine the baseline set of a property’s rule behaviors. (See the Products interface and Product object type.)

• Modules: Modules are add-ons to products that may enable additional rule behaviors. Different products support different sets of modules. Your ability to specify any given rule behavior depends on the currently active product and associated modules. PAPI does not provide information directly about your selected modules, but it does allow you to determine the currently available behaviors and criteria they enable.

The inputs above allow you to deploy properties:

• Properties: Akamai’s edge network caches your web assets near to servers that request them. A property, sometimes also referred to as a configuration, provides the main way to control how edge servers respond to various kinds of requests for those assets. Properties apply rules to a set of hostnames, and you can only apply one property at a time to any given hostname. Each property is assigned to a product, which determines which rule behaviors you can use. Each property’s default rule must specify a valid CP code to bill and report for the service. (See the Properties interface and Property object type.)

• Versions: Each property has snapshot versions, which allows you to modify one instance of a property while another is activated. You can freely modify a property version (along with its component hostnames and rules) up until the point at which it is activated, after which you must create a new version to modify it further. You do not need to create a new property version for each modification you make. Each version is identified by ascending integer, and features a time stamp, the username who modified it, and a log message. (See the Property Versions interface and Version object type.)

• Activations: Once you are satisfied with any version of a property, an activation deploys it, either to the Akamai staging or production network. You activate a specific version, but the same version can be activated separately more than once. You can cancel an activation shortly after enabling it, making it the only PAPI object you can delete. (See the Property Activations interface and Activation object type.)

• Metadata: Once activated, each property is distributed to the Akamai network as an XML configuration file known as Akamai metadata. This XML format combines information about the property’s rules and hostnames. You can view metadata for each version regardless of activation, but you can only modify it indirectly. (See the Property Versions interface.):

• Messages: When you modify different aspects of a property, responses may include errors or warnings. An error prevents you from activating a property version, but you can activate versions that yield less severe warnings. Warnings that result from activations must be explicitly acknowledged.

Properties include rules:

• Rules: Properties allow you to design rules to respond to different kinds of requests. A rule consists of criteria that identify which requests to process, and the behaviors to apply to those requests. In addition to a top-level default rule that determines overall behavior, you may include any number of your own rules, arranged in a tree structure up to five levels deep. The API provides an interface to the entire rule tree, not to each component rule. The API also does not support Control Center’s rule templates feature, since programming tools allow you to build your own rule templating system more flexibly. (See the Property Version Rules interface and Rule object type. See also the Rule Trees section for guidance on how to structure a rule tree.)

• Criteria: Rules may specify an optional set of criteria (often referred to as conditions or matches), based on which accompanying behaviors execute. (See the PAPI Feature Catalog Reference for information on all criteria the API makes available, and see the Rule Trees section for instructions on how to arrange them within JSON payloads.)

• Behaviors: Also referred to as features, these objects embedded within the rule tree instruct edge servers how to respond to requests. Your available set of behaviors depends on the selected product that enables the property. (See the PAPI Feature Catalog Reference for information on all behaviors the API makes available, and see the Rule Trees section for instructions on how to arrange them within JSON payloads.)

• Options: Most rule behaviors and criteria specify a set of options that determine how they operate. For example, most criteria check for a specific value option, and most behaviors feature an enabled option that turns them on or off. Despite the name, some options are actually required, often depending on values set by other options.

• Variables: Many behavior and criteria options allow you to inject variable text that interprets at runtime on edge servers, typically based on details about the client request. PAPI allows you to reference a set of built-in system variables, and create your own set of variables based on various inputs. (The Rules section discusses how to insert variables within a rule tree, and how to declare and modify your own variables.)

• Advanced Features: Most PAPI features translate to edge metadata in clearly prescribed ways. Functionality that falls outside what these predefined behaviors and criteria can do may be implemented as customized metadata. Advanced features are read-only, and require Akamai Professional Services to configure for you. In addition, you may request any feature with sensitive data to be locked for you. (The Rules section discusses advanced and locked features.)

• CP Codes: A content provider code is necessary to track all web traffic handled by Akamai servers. It is supplied to you when you purchase a product, and you need it to activate any associated properties. You can generate additional CP codes, typically to implement more detailed billing and reporting functions and assign to custom properties. Each property must specify at least one cpCode behavior as part of its default rule. (See the CP Codes interface and CpCode object type.)

• Schemas: Some errors may result when a request is not in the expected format. In that case, errors reference request schemas that represent the expected structure formatted as a JSON Schema object. (See the Schemas interface and Schema object type.)

• Rule Formats: You use rule formats to freeze or update the versioned set of behaviors and criteria a rule tree invokes. (Without this mechanism, behaviors and criteria would update automatically and generate unexpected errors.) 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. (See the operations to List Rule Formats and Get a Rule Format’s Schema. See also the operations that list currently available behaviors and criteria.)

• Client Settings: This API resource collects various configuration parameters for clients keyed to an authorization token. Currently it specifies only a single parameter: the default rule format version that is assigned to new properties.

Properties also include hostnames:

• Hostnames: Each property version applies its rules to requests for a set of hostnames under your control, such as www.example.com and m.example.com. This API interface specifies that set of hostnames. You also use this interface to specify whether each hostname only uses IPv4, or whether it also allows dual-stack IPv6 traffic. (See the Property Version Hostnames interface and data object type.)

• Edge Hostnames: Each hostname assigned to a property corresponds to an Akamai edge hostname, which is typically the hostname suffixed with edgesuite.net over HTTP or edgekey.net over secure HTTPS. For example, your source hostname m.example.com corresponds by default to the edge hostname m.example.com.edgesuite.net. This interface specifies the full set of edge hostnames under your control, regardless of how they are assigned to various properties or property versions. (See the Edge Hostnames interface and EdgeHostname object type.)

• CNAME: For a property to serve live traffic, you must first configure your DNS server so that requests for each hostname resolves to a corresponding edge hostname, the latter referred to as the canonical name. In turn, servers across the Akamai network use their own CNAME records to resolve these edge hostnames to more specific local server names and ultimately their IP addresses.

API versioning

The API exposes several different versioning systems:

• The version of the API is specified as part of the URL path. The current API version is v1.

• The API supports different dated versions for the set of features available within a property’s rule tree, for example: v2015-08-17. You can freeze and smoothly update the set of features that a property’s rules apply to your content. Each behavior and criteria you invoke within your rules may independently increment versions from time to time, but the API only allows you to specify the snapshot version for the entire set of features.

  Reference documentation for the latest set of features is available in the PAPI Feature Catalog Reference. For information on features specified by older rule formats, see the following:

  • PAPI Feature Catalog Reference, v2015–08–17

  • PAPI Feature Catalog Reference, v2016–11–15

  • PAPI Feature Catalog Reference, v2017–06–19

  • PAPI Feature Catalog Reference, v2018–02–27

• The API’s Build interface also provides details on the current software build and its accompanying catalog of behaviors and criteria. These include version numbers and extraneous commit and build dates, which bear no relation to dated rule format versions. Do not rely on any of the internal version numbers this interface makes available.

Expect internal catalog versions to update the most frequently, followed by less frequent rule format versions, followed by infrequent new API versions.

Data conventions

PAPI’s JSON data follows these overall conventions:

• When any response data can be singular or plural, it is always represented as an array to simplify client processing. This also applies to resources that only yield a single item.

• Parameter names always match member names in JSON requests and responses.

• Member names are fairly specific, for example propertyVersion rather than version.

PAPI applies the following JSON member naming conventions:

• *Name members are meant to be descriptive and human-readable (such as propertyName), and never need to appear as input to an endpoint.

• *Id members are machine-readable identifiers (such as propertyId) often used as inputs to endpoints. The values of *Id members use the following type prefixes to help distinguish them:

  • act_ prefix for accountId
  • ctr_ prefix for contractId
  • grp_ prefix for groupId
  • prd_ prefix for productId
  • prp_ prefix for propertyId
  • ehn_ prefix for edgeHostnameId
  • hst_ prefix for hostnameId
  • atv_ prefix for activationId
  • msg_ prefix for messageId
  • cpc_ prefix for cpcodeId

• *Date members represent date-time in ISO 8601 format using UTC timezone (such as updateDate). The API names all timestamps as *Date, they all use this same format.

• *Link members are URLs (such as activationLink) that respond to HTTP GET requests (described by a linked json-schema document). Since API hostnames are client-specific, URLs appear as absolute-path relative reference URLs, for example /papi/v0/properties rather than https://myclient.luna.akamaiapis.net/papi/v0/properties. Clients need to establish the base URL of links from the retrieval URL. The * part of the name can informally be considered the link relation.

NOTE: As a convenience, any response that provides a *Link JSON member also provides the same information in the Location HTTP header.

Rate and resource limiting

When working with any objects whose number is capped, X-Limit-prefixed HTTP headers provide that context in responses. Overall limits adhere to this format:

• X-Limit-Max-*-Limit
• X-Limit-Max-*-Remaining

Some limits may depend on other variables, such as the level of service included in your contract. These appear as:

• X-Limit-*-Per-*-Limit
• X-Limit-*-Per-*-Remaining

Anything that’s limited to periods of time uses this format, where Reset provides the epoch time at which the Remaining value resets to the overall Limit:

• X-RateLimit-*-Limit
• X-RateLimit-*-Remaining
• X-RateLimit-*-Reset

Note that you may have the option to override these limits. Contact your Akamai representative for more information.

PAPI reports the following set of contextual HTTP headers:

• X-Limit-Edgehostnames-Per-Contract-Limit
• X-Limit-Edgehostnames-Per-Contract-Remaining
• X-Limit-Properties-Per-Contract-Limit
• X-Limit-Properties-Per-Contract-Remaining
• X-Limit-Hosts-Per-Property-Limit
• X-Limit-Hosts-Per-Property-Remaining
• X-Limit-Clientip-Per-Property-Limit
• X-Limit-Clientip-Per-Property-Remaining
• X-Limit-Elements-Per-Property-Limit
• X-Limit-Elements-Per-Property-Remaining
• X-Limit-Max-Clientip-Per-Match-Limit
• X-Limit-Max-Clientip-Per-Match-Remaining
• X-Limit-Max-Nested-Rules-Limit
• X-Limit-Max-Nested-Rules-Remaining
• X-RateLimit-Activations-Limit
• X-RateLimit-Activations-Remaining
• X-RateLimit-Activations-Reset

Concurrency control

PAPI provides support for optimistic concurrency control on its property version, property hostname, and rule resources. When reading data from any of these resources, an opaque digest string representing a snapshot of the property version is available from the following:

• An etag object member.
• The double-quoted contents of the Etag HTTP header.

When performing any subsequent write operation (POST, PUT, PATCH, or DELETE), provide the same data as either of the following:

• An etag object member.
• The double-quoted contents of the If-Match HTTP header.

The request succeeds if the digest matches the current state of the resource’s data, otherwise it produces a 412 error. This prevents outdated representations from being used as the basis for updates when more than one client accesses the same resource. It keeps you from overwriting other users’ data, regardless of whether they access it with PAPI or Control Center’s Property Manager interface.

NOTE: Within the Etag or If-Match HTTP headers, the data digest must be double-quoted, or the request fails even if the digest otherwise appears to match. Also, you can only use the If-Match HTTP header when writing property hostnames, because that interface specifies an array, which can’t accommodate a top-level etags object member.

PAPI provides several other ways to use this mechanism:

• When creating a new property version, passing the request’s createFromVersionEtag member back in as an etag ensures the component hostnames or rules of the version on which it was based have not changed in the interim.

• When cloning a property, passing the request’s cloneFromVersionEtag member back in as an etag ensures the component hostnames or rules of the property version on which it was based have not changed in the interim.

PAPI tracks changes to data for the entire property version. Suppose you read a property version’s rule tree along with its etag digest. Another client then modifies the property version’s set of hostnames. When you write the rule tree back along with the etag, the request fails because one of the version’s components has been modified.

NOTE: The Network Lists API uses the term Sync Point to refer to the same concurrency control feature.

Validation and activation time

PAPI’s most important function is to modify rule trees associated with sets of hostnames, and to activate them on the edge. As described in the Rule Trees section, rule trees are potentially very large, complex objects that often require frequent, iterative optimizations.

Under PAPI’s traditional development cycle, each time you modify and save a rule tree, you would need to wait for a lengthy set of validation tests to complete, making an iterative development cycle more difficult. The current API release provides two shortcuts to speed up development:

• 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 is 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 JSON Problems section. Note that you still need to fix any errors, and to either fix or acknowledge any warnings. To get this information, you need to enable validation again before activating the property.

In general, expect validation to accelerate over time. Once a property is ready, the amount of time it takes to activate it across the Akamai network has also decreased dramatically. While activation times have been speeding up, they remain relatively slow in two cases:

• when you activate a property for the first time.

• whenever the set of deployed hostnames changes.

Contact your Akamai representative for guidance on latency for property activations.

Resources

This section provides details for the workflow through PAPI, and tells you how to interact with each operation. This provides you with a high-level overview to the PAPI workflow:

• Before running most other operations, you need to get a relevant contract and group. Before creating new objects, you also need a relevant product.

• See the operations listed in the CP Codes interface if you want to generate CP codes or find out which products they’re associated with.

• See the Edge Hostnames interface to deploy new hostnames on Akamai edge servers before assigning them to properties.

• See the Properties interface below if you want to access or create properties. See Property Versions if you want to create or access property instances. See Property Activations to deploy them to make your content available on Akamai’s edge network.

• See Property Version Rules if you want to access or modify the property’s rule tree, and Property Version Hostnames if you want to assign any edge hostnames.

• If you want to know which features you can assign within a rule tree, see List Available Behaviors and List Available Criteria.

• If you want more details about the underlying features that are applied as part of a property’s rule tree, List Rule Formats to get available versions of each versioned feature set, and Get a Rule Format’s Schema to validate a rule tree against a specific rule format.

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

See PAPI Concepts to learn more about how these resources relate to each other. For information on specific operations, the table below summarizes all of the basic actions the API enables, along with their corresponding combinations of methods and endpoints.

API summary

List groups

You need information about the prevailing group to access most PAPI interfaces. This operation provides a read-only list of groups, which may contain properties. (The User Admin API allows you to modify the group hierarchy.) This operation provides a flat list of groups, along with parentGroupId information to structure them as a hierarchy. Each group also lists any available contracts that enable property features, but not which group is associated with a given property. The User Admin API allows you to associate properties with groups.

{
    "accountId": "act_1-1TJZFB",
    "accountName": "Example.com",
    "groups": {
        "items": [
            {
                "groupName": "Example.com-1-1TJZH5",
                "groupId": "grp_15225",
                "contractIds": [ "ctr_1-1TJZH5" ]
            },
            {
                "groupName": "Test",
                "groupId": "grp_15231",
                "parentGroupId": "grp_15225",
                "contractIds": [ "ctr_1-1TJZH5" ]
            },
            {
                "groupName": "TomTest",
                "groupId": "grp_41443",
                "parentGroupId": "grp_15225",
                "contractIds": [ "ctr_1-1TJZH5" ]
            }
        ]
    }
}

List contracts

You need information about the prevailing contract to access most PAPI interfaces. This operation provides a read-only list of contract names and identifiers. The response provides context on the overall account (prefixed act_) that enables each contract and keys your API credentials, but you do not need it to access any PAPI objects.

{
    "accountId": "act_1-1TJZFB",
    "contracts": {
        "items": [
            {
                "contractId": "ctr_1-1TJZH5",
                "contractTypeName": "Direct Customer"
            }
        ]
    }
}

List products

This operation lists the set of products that are available under a given contract. You need a product identifier to create new edge hostnames, CP codes, or properties. The range of rule behaviors available within a property is determined by the assigned product.

{
    "accountId": "act_1-1TJZFB",
    "contractId": "ctr_1-1TJZH5",
    "products": {
        "items": [
            {
                "productName": "Alta",
                "productId": "prd_Alta"
            }
        ]
    }
}

List CP codes

This operation lists CP codes available within your contract/group pairing, which you assign to a property within its rule tree. CP codes include information about the product under which they were generated. When creating a new property, you should apply the same product under which the associated CP code was created.

{
    "accountId": "act_1-1TJZFB",
    "contractId": "ctr_1-1TJZFW",
    "groupId": "grp_15225",
    "cpcodes": {
        "items": [
            {
                "cpcodeId": "cpc_33190",
                "cpcodeName": "SME WAA",
                "productIds": [ "prd_Web_App_Accel" ],
                "createdDate": "2015-03-02T15:06:13Z"
            }
        ]
    }
}

Create a new CP code

To create a new CP code, you need to associate it with a product. You can assign any CP code within a property’s rule tree as detailed in the Rule Trees section. You should match the same productId that’s assigned to properties that invoke the CP code to the one assigned to the CP code, otherwise you may get a warning.

{
    "productId": "prd_Web_App_Accel",
    "cpcodeName": "SME WAA"
}

{
    "cpcodeLink": "/papi/v0/cpcodes/cpc_33190?contractId=ctr_1-1TJZFW&groupId=grp_15166"
}

Get a CP code

This operation gets details about a CP code.

{
    "accountId": "act_1-1TJZFB",
    "contractId": "ctr_1-1TJZFW",
    "groupId": "grp_15166",
    "cpcodes": {
        "items": [
            {
                "cpcodeId": "cpc_33190",
                "cpcodeName": "SME WAA",
                "productIds": [ "prd_Web_App_Accel" ],
                "createdDate": "2015-03-02T15:06:13Z"
            }
        ]
    }
}

List edge hostnames

This lists all edge hostnames available under a contract. You assign these hostnames to a property as a separate operation.

{
    "accountId": "act_1-1TJZFB",
    "contractId": "ctr_1-1TJZH5",
    "groupId": "grp_15225",
    "edgeHostnames": {
        "items": [
            {
                "edgeHostnameId": "ehn_895822",
                "edgeHostnameDomain": "example.com.edgekey.net",
                "productId": "prd_Alta",
                "domainPrefix": "example.com",
                "domainSuffix": "edgekey.net",
                "status": "PENDING",
                "secure": true,
                "ipVersionBehavior": "IPV4",
                "mapDetails:serialNumber": 79,
                "mapDetails:slotNumber": 11,
                "mapDetails:mapDomain": "e79.x.akamaiedge.net"
            },
            {
                "edgeHostnameId": "ehn_887436",
                "edgeHostnameDomain": "example.com.edgesuite.net",
                "productId": "prd_Alta",
                "status": "ACTIVE",
                "domainPrefix": "example.com",
                "domainSuffix": "edgesuite.net",
                "secure": false,
                "ipVersionBehavior": "IPV4",
                "mapDetails:serialNumber": 1951,
                "mapDetails:mapDomain": "a1951.g.akamai.net"
            }
        ]
    }
}

Create a new edge hostname

This operation creates a new edge hostname. Once the hostname is active, you can assign it to a property. After activating the property, modifying your DNS to map the origin hostname to the edge hostname ultimately enables traffic. See Enable Traffic for a New Edge Hostname for details.

Note that PAPI does not allow you to create new secure edge hostnames, but you can do this using the Secure Provisioning Service API. Once secure hostnames are queued, list all the edge hostnames in PAPI to confirm their activation status.

{
    "productId": "prd_PPP",
    "domainPrefix": "www.example.com",
    "domainSuffix": "edgesuite.net",
    "secure": true,
    "ipVersionBehavior": "IPV4",
    "slotNumber": 12345
}

{
    "edgeHostnameLink": "/papi/v0/edgehostnames/ehn_1332?contractId=ctr_1-1TJZH5&grp_15225"
}

Enable traffic for a new edge hostname

After creating a new edge hostname, assigning it to a property, and activating the property, you still need to modify your DNS configuration to direct the origin’s traffic to the new edge hostname, otherwise known as Akamaizing your content.

Edge hostnames are formed from the combined domainPrefix and domainSuffix included in the POST request, in this case custom.example.com.edgesuite.net to indicate standard HTTP traffic:

{
    "productId": "prd_PPP",
    "domainPrefix": "custom.example.com",
    "domainSuffix": "edgesuite.net",
    "secure": true,
    "ipVersionBehavior": "IPV4",
    "slotNumber": 12345
}

(HTTPS typically uses an edgekey.net suffix.) The POST request tells Akamai’s network of DNS servers to map it to local server names, but for the hostname to ultimately activate, you need to update your own DNS record to map your origin hostname to the edge hostname. A resulting DNS resolution looks like this:

$ host -v custom.example.com
Trying "custom.example.com"
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 14682
;; flags: qr aa rd ra; QUERY: 1, ANSWER: 3, AUTHORITY: 0, ADDITIONAL: 0

;; QUESTION SECTION:
;custom.example.com.            IN      A

;; ANSWER SECTION:
custom.example.com.     300     IN      CNAME   custom.example.com.edgekey.net.
custom.example.com.edgekey.net. 3701 IN CNAME   e79.x.akamaiedge.net.
e79.x.akamaiedge.net.   11      IN      A       72.246.8.105

The first CNAME entry maps your custom.example.com domain to the edge hostname custom.example.com.edgekey.net, required for traffic to flow to the edge hostname. POSTing the new edge hostname implements the second CNAME, which in this case maps the edge hostname to the local hostname e79.x.akamaiedge.net, and in turn to a local IP address.

Get an edge hostname

This polls the state of an edge hostname, typically after creating a new edge hostname. The response tells you whether the CNAME has been fully distributed across the network. If the hostname’s status is ACTIVE, the process is complete. Until then, you typically see values of ZONE1, ZONE2, ZONE3, or simply PENDING.

{
    "accountId": "act_1-1TJZFB",
    "contractId": "ctr_1-1TJZH5",
    "groupId": "grp_15225",
    "edgeHostnames": {
        "items": [
            {
                "edgeHostnameId": "ehn_887436",
                "edgeHostnameDomain": "example.com.edgesuite.net",
                "productId": "prd_Alta",
                "status": "ACTIVE",
                "domainPrefix": "example.com",
                "domainSuffix": "edgesuite.net",
                "secure": false,
                "ipVersionBehavior": "IPV4",
                "mapDetails:serialNumber": 1951,
                "mapDetails:mapDomain": "a1951.g.akamai.net"
            }
        ]
    }
}

List properties

This operation lists properties available for the current contract and group.

{
    "properties": {
        "items": [
            {
                "accountId": "act_1-1TJZFB",
                "contractId": "ctr_1-1TJZH5",
                "groupId": "grp_15225",
                "propertyId": "prp_175780",
                "propertyName": "example.com",
                "latestVersion": 2,
                "stagingVersion": 1,
                "productionVersion": null,
                "note": "Notes about example.com"
            },
            {
                "accountId": "act_1-1TJZFB",
                "contractId": "ctr_1-1TJZH5",
                "groupId": "grp_15225",
                "propertyId": "prp_175781",
                "propertyName": "m.example.com",
                "latestVersion": 1,
                "stagingVersion": null,
                "productionVersion": null,
                "note": "Notes about m.example.com"
            }
        ]
    }
}

Create or clone a property

This operation either creates a new property from scratch, or bases one on another property’s rule tree and optionally its set of assigned hostnames.

{
    "productId": "prd_Alta",
    "propertyName": "my.new.property.com",
    "cloneFrom": {
        "propertyId": "prp_175780",
        "version": 2,
        "cloneFromVersionEtag": "a9dfe78cf93090516bde891d009eaf57",
        "copyHostnames": true
    }
}

{
    "propertyLink": "/papi/v0/properties/prp_173137?contractId=ctr_1-1TJZH5&groupId=grp_15225"
}

When cloning with copyHostnames enabled, you can apply the same set of hostnames as the original property. Regardless, the new property clones the rule tree from the original, along with its assigned ruleFormat. Setting cloneFromVersionEtag allows you to perform an etags check to ensure the original property has not changed.

Note that unlike a new property version, a property that you clone along with all of its hostnames can be activated independently of the property on which it was based. If you activate a property that specifies hostnames that are already active on another property, the other property automatically gets a new version activated without the common set of hostnames, or deactivated if all its hostnames are part of the new property.

PAPI’s ability to create and clone new properties means that you can design a system of rule templates targeted to specific domains, rather than maintain a single set of rules with conditional logic for your full range of domains. Maintaining properties manually within Control Center limited you to that more consolidated approach, but PAPI allows you to deploy rules more efficiently. In either case, PAPI makes it much easier for you to support a large, flexible set of domains.

Get a property

This operation gets a specific property. You can call this operation by specifying any of the propertyId members from a list of properties, or by running a GET on the propertyLink response when creating a new property:

{
    "properties": {
        "items": [
            {
                "accountId": "act_1-1TJZFB",
                "contractId": "ctr_1-1TJZH5",
                "groupId": "grp_15225",
                "propertyId": "prp_175780",
                "propertyName": "example.com",
                "latestVersion": 2,
                "stagingVersion": 1,
                "productionVersion": null,
                "note": "Notes about example.com"
            }
        ]
    }
}

Remove a property

Removes a specific property, which you can only do if none of its versions are currently active. Activating another property with the same set of hostnames automatically triggers a deactivation on the targeted property. See Create a New Activation for details.

A successful DELETE results in a 200 response with the link to the remaining properties for the given contract and group. Attempting to delete an active property results in a 666 error. Attempting to delete an unknown property results in a 404 error.

{
    "message" : "Deletion Successful."
}

List versions

List all versions of a property. Each property version indicates activation status on different networks, and an etag digest useful in cloning the property.

{
    "propertyId": "prp_173136",
    "propertyName": "981.catalog.amenai.net",
    "accountId": "act_1-1TJZFB",
    "contractId": "ctr_1-1TJZH5",
    "groupId": "grp_15225",
    "versions": {
        "items": [
            {
                "propertyVersion": 2,
                "updatedByUser": "amenai",
                "updatedDate": "2014-05-10T19:06:13Z",
                "productionStatus": "INACTIVE",
                "stagingStatus": "ACTIVE",
                "etag": "5891b5b522d5df08",
                "productId": "prd_Alta",
                "note": "updated caching"
            },
            {
                "propertyVersion": 1,
                "updatedByUser": "afaden",
                "updatedDate": "2013-05-04T21:12:57Z",
                "productionStatus": "ACTIVE",
                "stagingStatus": "INACTIVE",
                "etag": "71573b922a87abc3",
                "productId": "prd_Alta",
                "note": "initial version"
            }
        ]
    }
}

Create a new version

Create a new property version based on any previous version. All data from the createFromVersion populates the new version, including its rules and hostnames. Specify createFromVersionEtag if you want to ensure you are creating from a version that has not changed since you fetched it.

{
    "createFromVersion": 1,
    "createFromVersionEtag": "2641910c585cf67b"
}

{
    "versionLink": "/papi/v0/properties/prp_173136/versions/2?contractId=ctr_1-1TJZH5&groupId=grp_15225"
}

Get a version

This polls the state of a specific property version, for example to check its activation status.

When specifying Accept: text/xml, this resource provides the Akamai metadata configuration data that is distributed to edge servers when the property version is activated. This XML data encapsulates the property version’s component rules and hostnames, and is available on a read-only basis. Contact your Akamai representative if you need help interpreting it.

{
    "propertyId": "prp_173136",
    "propertyName": "981.calatog.amenai.net",
    "accountId": "act_1-1TJZFB",
    "contractId": "ctr_1-1TJZH5",
    "groupId": "grp_15225",
    "versions": {
        "items": [
            {
                "propertyVersion": 1,
                "updatedByUser": "afaden",
                "updatedDate": "2014-03-04T21:12:57Z",
                "productionStatus": "ACTIVE",
                "stagingStatus": "INACTIVE",
                "etag": "71573b922a87abc3",
                "productId": "prd_Alta",
                "ruleFormat": "latest",
                "note": "initial version"
            }
        ]
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<configs xmlns:cache="uri:akamai.com/metadata/cache/5.0" xmlns:edgeservices="uri:akamai.com/metadata/edgeservices/5.0" xmlns:config="uri:akamai.com/metadata/config/5.0" xmlns:network="uri:akamai.com/metadata/network/5.0" xmlns:auth="uri:akamai.com/metadata/auth/5.0" xmlns:match="uri:akamai.com/metadata/match/5.0" xmlns:forward="uri:akamai.com/metadata/forward/5.0" xmlns:comment="uri:akamai.com/metadata/comment/5.0" xmlns:akamai="uri:akamai.com/metadata/akamai/5.0" xmlns:security="uri:akamai.com/metadata/security/5.0" xmlns:reporting="uri:akamai.com/metadata/reporting/5.0" xmlns:edgecomputing="uri:akamai.com/metadata/edgecomputing/5.0" xmlns:assign="uri:akamai.com/metadata/assign/5.0">
    <comment:note value="Property Manager generated metadata. XML engine version: 14.2.1"/>
    <comment:note value="Catalog version: 14.4.4"/>
    <comment:note value="Product name: Site_Accel"/>
    <comment:note value="Property name: example.com, version: 33"/>
    <comment:note value="Asset ID: 99999"/>
    <comment:note value="AcgID: "/>
    <comment:note value="AccountId: 1-7KLGH"/>
    <comment:note value="Hostnames: www.example.com"/>
</configs>

Get the latest version

This operation provides either the latest property version overall, or the latest one active on the production or staging networks. By default, the response yields the property version with the highest number. Specifying an activatedOn of STAGING or PRODUCTION yields the version that’s currently active on either network.

{
    "versionLink": "/papi/v0/properties/prp_173136/versions/2?contractId=ctr_1-1TJZH5&groupId=grp_15225"
}

List available behaviors

Lists behaviors you may apply within a property version’s rules. The available set is determined by the product under which you created the property, and any additional modules enabled under your account.

Note that this list of available behaviors is more accurate than that specified in the rule format schema, which includes behaviors you may potentially add to your contract for a given product, but that are not currently active. However, it only lists behaviors currently available on your contract, so you should only use it to list available behaviors for the current property version. If you had a behavior enabled at one time, but then dropped it from your contract, a list of available behaviors for an older property version might be inaccurate.

{
    "contractId": "ctr_1-1TJZH5",
    "groupId": "grp_15225",
    "productId": "prd_Alta",
    "ruleFormat": "v2015-08-08",
    "availableBehaviors": {
        "items": [
            {
                "name": "cpCode",
                "schemaLink": "/papi/v0/schemas/products/prd_Alta/latest#/definitions/catalog/behaviors/cpCode"
            },
            {
                "name": "origin",
                "schemaLink": "/papi/v0/schemas/products/prd_Alta/latest#/definitions/catalog/behaviors/origin"
            }
        ]
    }
}

List available criteria

Lists criteria you may apply within a property version’s rules. The available set is determined by the product under which you created the property, and any additional modules enabled under your account.

Note that this list of available criteria is more accurate than that specified in the rule format schema, which includes criteria you may potentially add to your contract for a given product, but that are not currently active. However, it only lists criteria currently available on your contract, so you should only use it to list available criteria for the current property version. If you had a behavior enabled at one time, but then dropped it from your contract, a list of available criteria for an older property version might be inaccurate.

{
    "contractId": "ctr_1-1TJZH5",
    "groupId": "grp_15225",
    "productId": "prd_Alta",
    "ruleFormat": "v2015-08-08",
    "availableCriteria": {
        "items": [
            {
                "name": "fileExtension",
                "schemaLink": "/papi/v0/schemas/products/prd_Alta/latest#/definitions/catalog/criteria/fileExtension"
            },
            {
                "name": "hostname",
                "schemaLink": "/papi/v0/schemas/products/prd_Alta/latest#/definitions/catalog/criteria/hostname"
            }
        ]
    }
}

List a property’s hostnames

This lists all the hostnames assigned to a property version, which may be a subset of all available edge hostnames.

{
    "accountId": "act_1-1TJZFB",
    "contractId": "ctr_1-1TJZH5",
    "groupId": "grp_15225",
    "propertyId": "prp_175780",
    "propertyVersion": 1,
    "etag": "6aed418629b4e5c0",
    "hostnames": {
        "items": [
            {
                "cnameType": "EDGE_HOSTNAME",
                "edgeHostnameId": "ehn_895822",
                "cnameFrom": "example.com",
                "cnameTo": "example.com.edgesuite.net"
            },
            {
                "cnameType": "EDGE_HOSTNAME",
                "edgeHostnameId": "ehn_895833",
                "cnameFrom": "m.example.com",
                "cnameTo": "m.example.com.edgesuite.net"
            }
        ]
    }
}

Update a property’s hostnames

Modify the set of hostname entries for a property version. For each hostname entry, the cnameFrom is required along with either the cnameTo or edgeHostnameId.

There are no POST or DELETE operations to add or remove hostnames from a property, so to assign them you need to make a PUT request that specifies the entire set as an array. Since the data sent in the PUT request is an array, adding an If-Match HTTP header is the only way to prevent overwriting edits from another client. See Concurrency Control for more information on this technique.

If you activate a property version that specifies a hostname already active on another property, it is removed from that property, and a new property version is automatically created and activated with the change. Otherwise you do not receive any warning when saving a set of overlapping hostnames on an inactive version.

Set the validateHostnames query parameter to false to bypass a set of validation tests that may significantly slow this operation’s execution time. See Validation and Activation Time for guidance on when to defer validation. See JSON Problems for information on how validation data is embedded within the response object.

[
    {
        "cnameType": "EDGE_HOSTNAME",
        "cnameFrom": "m.example.com",
        "cnameTo": "example.com.edgesuite.net"
    },
    {
        "cnameType": "EDGE_HOSTNAME",
        "edgeHostnameId": "ehn_895824",
        "cnameFrom": "example3.com"
    }
]

{
    "accountId": "act_1-1TJZFB",
    "contractId": "ctr_1-1TJZH5",
    "groupId": "grp_15225",
    "propertyId": "prp_175780",
    "propertyVersion": 1,
    "etag": "6aed418629b4e5c0",
    "hostnames": {
        "items": [
            {
                "cnameType": "EDGE_HOSTNAME",
                "edgeHostnameId": "ehn_895822",
                "cnameFrom": "example.com",
                "cnameTo": "example.com.edgesuite.net"
            },
            {
                "cnameType": "EDGE_HOSTNAME",
                "edgeHostnameId": "ehn_895833",
                "cnameFrom": "m.example.com",
                "cnameTo": "m.example.com.edgesuite.net"
            }
        ]
    }
}

Get a rule tree

This gets the entire rule tree for a property version. See the Rule Trees section for details on the response object’s structure. Also use this operation to update from one rule format to another more recent version, incrementing the assigned set of features. See Update Rules to a Newer Set of Features below.

{
    "accountId": "act_1-1TJZFB",
    "contractId": "ctr_1-1TJZH5",
    "groupId": "grp_15225",
    "propertyId": "prp_173136",
    "propertyVersion": 3,
    "etag": "a9dfe78cf93090516bde891d009eaf57",
    "ruleFormat": "v2015-08-08",
    "rules": {
        "name": "default",
        "options": { "is_secure": false },
        "criteria": [],
        "behaviors": [
            {
                "name": "origin",
                "options": {
                    "http_port": "80",
                    "tcip_enabled": "off",
                    "compression": "on",
                    "cachekeyhostname": "originhostname",
                    "forwardhostheader": "requesthostheader",
                    "hostname": "origin.test.com",
                    "type": "customer"
                }
            },
            {
                "name": "cpCode",
                "options": { "cpcodeId": 12345 }
            }
        ],
        "children": []
    }
}

Update rules to a newer set of features

This section describes a specific use for the Get a Rule Tree operation described above: to increment 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.

Use this procedure to update from one rule format to another more recent version, incrementing the assigned set of features. 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 the more recent rule format version string 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 rule format version string.

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 retrieved 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 does not 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. In these cases the PUT response’s rule tree object includes errors that help you refine the updated rule tree, as detailed in the Errors section.

Get a rule tree’s digest

This operation retrieves the rule tree’s Etag without the rule tree object. Ordinarily when you get a rule tree, the response includes a large rule tree object. As discussed in Concurrency Control, it includes a top-level etag data digest to use when writing back the data. Use this operation if you simply want to retrieve the Etag as a header without retrieving the data.

Update a rule tree

To write a rule tree to a property version, make a PUT request to the same resource as the GET request that reads it, passing in the rule object in the body of the request. See the Rule Trees section for details on the rule tree’s structure. Use this operation also to freeze a set of rules to a rule format version to ensure no change in a deployed activation’s behavior. Set the validateRules query parameter to false to bypass a set of validation tests that may significantly slow this operation’s execution time. See Validation and Activation Time for guidance on when to defer validation. See JSON Problems for information on how validation data is embedded within the response object.

{
    "rules": {
        "name": "default",
        "children": [
            {
                "name": "Handle /my-path",
                "criteriaMustSatisfy": "all",
                "criteria": [
                    {
                        "name": "path",
                        "value": [ "/my-path" ]
                    }
                ],
                "behaviors": [
                    {
                        "name": "caching",
                        "behavior": "max-age",
                        "ttl": "1m"
                    }
                ]
            }
        ]
    }
}

{
    "accountId": "act_1-1TJZFB",
    "contractId": "ctr_1-1TJZH5",
    "groupId": "grp_15225",
    "propertyId": "prp_173136",
    "propertyVersion": 3,
    "etag": "a9dfe78cf93090516bde891d009eaf57",
    "errors": [
        {
            "type": "/papi/v0/errors/validation.required_behavior",
            "title": "Missing required behavior in default rule",
            "detail": "In order for this property to work correctly behavior Content Provider Code needs to be present in the default section",
            "instance": "/papi/v0/properties/prp_173136/versions/3/rules#err_100",
            "behaviorName": "cpCode"
        },
        {
            "type": "/papi/v0/errors/validation.required_behavior",
            "title": "Missing required behavior in default rule",
            "detail": "In order for this property to work correctly behavior Origin needs to be present in the default section",
            "instance": "/papi/v0/properties/prp_173136/versions/3/rules#err_101",
            "behaviorName": "origin"
        }
    ],
    "rules": {
        "name": "default",
        "children": [
            {
                "name": "Handle /my-path",
                "criteriaMustSatisfy": "all",
                "criteria": [
                    {
                        "name": "path",
                        "value": [ "/my-path" ]
                    }
                ],
                "behaviors": [
                    {
                        "name": "caching",
                        "behavior": "max-age",
                        "ttl": "1m"
                    }
                ]
            }
        ]
    }
}

Freeze a rule tree’s feature set

This section describes a specific use for the Update a Rule Tree operation described above: 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.

Rule trees are best deployed by assigning them a rule format that specifies a fixed, frozen set of features that are guaranteed not to change unexpectedly over time and cause errors. 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. GET the rule tree and store the URL you use to retrieve 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 is latest.

3. List available 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 object to the same URL you used to retrieve 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 does not conform to the associated rule format schema, the response includes errors that may prevent you from activating the property.

Search properties

This operation searches properties by name, or by the hostname or edge hostname for which it is currently active. Specify a request object with a single propertyName, hostname, or edgeHostname value. The response lists the matching set of currently active property versions. Each of the response’s Version objects features additional context for the property in which it appears, or the account, contract, or group under which the property was provisioned.

{
    "edgeHostname": "my-hostname-1.example.com.edgesuite.net"
}

{
    "versions": {
        "items": [
            {
                "accountId": "act_1-1TJZFB",
                "contractId": "ctr_1-1TJZH5",
                "groupId": "grp_15225",
                "propertyId": "prp_173136",
                "propertyName": "981.catalog.amenai.net",
                "propertyVersion": 2,
                "updatedByUser": "amenai",
                "updatedDate": "2014-05-10T19:06:13Z",
                "productionStatus": "INACTIVE",
                "stagingStatus": "ACTIVE",
                "note": "updated caching",
                "hostname": "non-null-hostname-for-hostname-searches",
                "edgeHostname": "non-null-edge-hostname-for-hostname-searches"
            },
            {
                "accountId": "act_1-1TJZFB",
                "contractId": "ctr_1-1TJXYZ",
                "groupId": "grp_15226",
                "propertyId": "prp_173137",
                "propertyName": "a-different-property.net",
                "propertyVersion": 1,
                "updatedByUser": "afaden",
                "updatedDate": "2013-05-04T21:12:57Z",
                "productionStatus": "ACTIVE",
                "stagingStatus": "INACTIVE",
                "note": "initial version",
                "hostname": "non-null-hostname-for-hostname-searches",
                "edgeHostname": "non-null-edge-hostname-for-hostname-searches"
            }
        ]
    }
}

List activations

This lists all activations for all versions of a property, on both production and staging networks.

{
    "accountId": "act_1-1TJZFB",
    "contractId": "ctr_1-1TJZH5",
    "groupId": "grp_15225",
    "activations": {
        "items": [
            {
                "activationId": "atv_1696985",
                "propertyName": "example.com",
                "propertyId": "prp_173136",
                "propertyVersion": 1,
                "network": "STAGING",
                "activationType": "ACTIVATE",
                "status": "ACTIVE",
                "submitDate": "2014-03-05T02:22:12Z",
                "updateDate": "2014-03-04T21:12:57Z",
                "note": "Sample activation",
                "notifyEmails": [
                    "you@example.com",
                    "them@example.com"
                ]
            },
            {
                "activationId": "atv_1696986",
                "propertyName": "example.com",
                "propertyId": "prp_173136",
                "propertyVersion": 1,
                "network": "PRODUCTION",
                "activationType": "ACTIVATE",
                "status": "ACTIVE",
                "submitDate": "2014-03-02T02:22:12Z",
                "updateDate": "2014-03-01T21:12:57Z",
                "note": "Sample activation",
                "notifyEmails": [
                    "you@example.com",
                    "them@example.com"
                ]
            }
        ]
    }
}

Activate a property

This operation creates a new property activation, which deactivates any current activation. After a necessary delay, this activates your property version’s rule tree and set of hostnames across Akamai’s network of edge servers, modifying how your edge content responds to end-user requests.

If the activation request produces warnings, a 400 response indicates this problem message: {"type": "/papi/v0/activation-warnings-not-acknowledged"}. Subsequent requests succeed if you list the messageId values in the request’s acknowledgeWarnings array. Once an activation is successful, it responds with a 201 code and provides a Location header and activationLink in the response object indicating where to poll the status of the activation.

NOTE: If you set activationType to DEACTIVATE in the POST request object, the property would deactivate and no longer serve any traffic. You would need to modify (de-Akamaize) your DNS configuration and specify a different way to handle the traffic. See Enable Traffic for a New Edge Hostname for more information.

{
    "propertyVersion": 1,
    "network": "STAGING",
    "note": "Sample activation",
    "notifyEmails": [
        "you@example.com",
        "them@example.com"
    ],
    "acknowledgeWarnings": [
        "msg_baa4560881774a45b5fd25f5b1eab021d7c40b4f"
    ]
}

{
    "activationLink": "/papi/v0/properties/prp_173136/activations/atv_67037?contractId=ctr_1-1TJZFB&groupId=grp_15225"
}

Get an activation

Gets details about an activation. You typically get a single activation from an activationLink when launching a new activation and following up to poll its status. For activations whose status is PENDING, a Retry-After header provides an estimate for when it’s likely to change.

{
    "activations": {
        "items": [
            {
                "activationId": "atv_1696985",
                "propertyName": "example.com",
                "propertyId": "prp_173136",
                "propertyVersion": 1,
                "network": "STAGING",
                "activationType": "ACTIVATE",
                "status": "PENDING",
                "submitDate": "2014-03-02T02:22:12Z",
                "updateDate": "2014-03-01T21:12:57Z",
                "note": "Sample activation",
                "notifyEmails": [
                    "you@example.com",
                    "them@example.com"
                ],
                "accountId": "act_1-1TJZFB",
                "groupId": "grp_15225"
            }
        ]
    }
}

Cancel a pending activation

If you detect a problem with a property version while its activation is still PENDING, this operation allows you to cancel it. Make a DELETE request on the response’s activationLink from running Activate a Property. Once you DELETE the activation, it no longer appears in the list of activations, but you can still access it individually.

A successful cancellation results in a 200 response and an ABORTED status. If the activation is no longer PENDING, a 422 (unprocessable) error indicates that it can no longer be canceled. Canceling an activation that has already been canceled results in a 204 response, indicating there’s no resource to delete. Canceling an unknown activation results in a 404 error.

You can only abort an activation while it’s queued for deployment across the various network zones with PENDING status. Once the window has closed and it’s been dispatched across the network, you can either reactivate an older version, or create a new version that fixes the problem and activate that instead.

{
    "activations": {
        "items": [
            {
                "activationId": "atv_1696985",
                "propertyName": "example.com",
                "propertyId": "prp_173136",
                "propertyVersion": 1,
                "network": "STAGING",
                "activationType": "ACTIVATE",
                "status": "ABORTED",
                "submitDate": "2014-03-02T02:22:12Z",
                "updateDate": "2014-03-01T21:12:57Z",
                "note": "Sample activation cancellation",
                "notifyEmails": [
                    "you@example.com",
                    "them@example.com"
                ],
                "accountId": "act_1-1TJZFB",
                "groupId": "grp_15225"
            }
        ]
    }
}

List rule formats

Gets a list of available rule formats. These dated version strings available in the response’s ruleFormats.items array allow you to control the set of behaviors and criteria you invoke within a property’s rules to apply to edge content, either freezing a rule tree or updating to a new rule format. To validate a rule tree to the requirements of a specific rule format, see Get a Rule Format’s JSON Schema.

{
    "ruleFormats": {
        "items": [
            "latest",
            "v2015-08-08"
        ]
    }
}

Get a request’s schema

Fetch the JSON schema for a particular request. These are typically linked from error messages about schema mismatches.

{
    "type": "object"
}

Get a rule format’s schema

Get the JSON schema for the given product and rule format, which you can use to validate a rule tree object.

NOTE: Your rule tree may still fail to activate if you specify features that are optional within the schema for a product but not currently supported on your contract. To validate the set of currently available features you want to activate, run List Available Behaviors and List Available Criteria.

{
    "type": "object",
    "properties": {
        "rules": { "type": "object" }
    },
    "required": [ "rules" ]
}

Get client settings

Get the current set of default values that apply to API clients keyed by the current authorization token. This operation currently has one use: to access the dated rule format version for a set of features assigned by default to new properties’ rule trees.

{
    "ruleFormat": "v2015-08-08"
}

Update client settings

Update the current set of default values that apply to API clients keyed by the current authorization token. This operation currently has one use: to update the dated rule format version for a set of features assigned by default to new properties’ rule trees.

{
    "ruleFormat": "v2015-08-08"
}

{
    "ruleFormat": "v2015-08-08"
}

Get build details

Gets information about the current API release. Note that available information about version numbers and build dates are unrelated to the overall API version or to various rule format versions. See API Versioning for details.

{
    "catalogGitInfo": {
        "buildDate": "2014-05-26T23:56:21Z",
        "commitDate": "2014-05-26T23:55:53Z",
        "branch": "candidate-14.2",
        "commitId": "59a193acdf26ba6de1522486411a749f19efde8c"
    },
    "coreGitInfo": {
        "buildDate": "2014-04-25T17:02:43Z",
        "commitDate": "2014-04-25T17:01:11Z",
        "branch": "14.2",
        "commitId": "22163903cb91a62492dfce745aaa95de991b0653"
    },
    "currentCatalogVersion": "14.2.6",
    "coreVersion": "14.2"
}

Data

This section describes Property Manager API’s various data structures.

Most of the API’s JSON objects are structured as wrappers whose high-level members provide overall context for the request. The following contextual members may appear within this top-level object:

As described in the Data Conventions section, relevant data for most resources is available within a nested items array, even if the request yields a single record. When writing to the API, you often POST these smaller objects rather than perform a PUT on the entire data structure. For example, a GET may yield this hypothetical data structure:

{
    "contextualMember": true,
    "nouns": {
        "items": [
            { "nounName": "resource" }
        ]
    }
}

To write new data, you would POST only the inner object to the same endpoint:

{ "nounName": "endpoint" }

See the Resources section for samples of JSON data.

Group

Encapsulates information about the group that contains a property and allows it to be deployed. See the List Groups operation for a detailed interaction.

Sample GET response:

{
    "accountId": "act_1-1TJZFB",
    "accountName": "Example.com",
    "groups": {
        "items": [
            {
                "groupName": "Example.com-1-1TJZH5",
                "groupId": "grp_15225",
                "contractIds": [
                    "ctr_1-1TJZH5"
                ]
            },
            {
                "groupName": "Test",
                "groupId": "grp_15231",
                "parentGroupId": "grp_15225",
                "contractIds": [
                    "ctr_1-1TJZH5"
                ]
            }
        ]
    }
}

Group members

The top-level JSON object features the following outer contextual members:

• accountId
• accountName

The groups member is an object whose nested items array lists each group. These objects contain the following members:

Contract

Encapsulates information about the contract under which a property may be deployed. See the List Contracts operation for a detailed interaction.

Sample GET response:

{
    "accountId": "act_1-1TJZFB",
    "contracts": {
        "items": [
            {
                "contractId": "ctr_1-1TJZH5",
                "contractTypeName": "Direct Customer"
            }
        ]
    }
}

Contract members

The top-level JSON object features the following outer contextual member:

• accountId

The contracts member is an object whose nested items array lists each contract. These objects contain the following members:

Product

Encapsulates information on the product that determines a property’s available range of features. See the List Products operation for a detailed interaction.

Sample GET response:

{
    "accountId": "act_1-1TJZFB",
    "contractId": "ctr_1-1TJZH5",
    "products": {
        "items": [
            {
                "productName": "Alta",
                "productId": "prd_Alta"
            }
        ]
    }
}

Product members

The top-level JSON object features the following outer contextual members:

• accountId
• contractId

The products member is an object whose nested items array lists each product. These objects contain the following members:

CpCode

Specifies billing and reporting codes. See the CP Codes interface for detailed interactions.

Sample GET response:

{
    "accountId": "act_1-1TJZFB",
    "contractId": "ctr_1-1TJZFW",
    "groupId": "grp_15225",
    "cpcodes": {
        "items": [
            {
                "cpcodeId": "cpc_33190",
                "cpcodeName": "SME WAA",
                "productIds": ["prd_Web_App_Accel"],
                "createdDate": "2015-03-02T15:06:13Z"
            }
        ]
    }
}

Sample POST request:

{
        "productId"  : "prd_Obj_Caching",
        "cpcodeName" : "g2o"
}

CpCode members

The top-level JSON object features the following outer contextual members:

• accountId
• contractId
• groupId

The cpcodes member is an object whose nested items array lists each CP code. These objects contain the following members:

To make a POST request that creates a new CP code, specify a single cpcode object with the required productId and cpcodeName members.

EdgeHostname

Specifies a set of available hostnames to which a property version may be applied. See the Edge Hostnames interface for detailed interactions.

Sample GET response:

{
    "accountId": "act_1-1TJZFB",
    "contractId": "ctr_1-1TJZH5",
    "groupId": "grp_15225",
    "edgeHostnames": {
        "items": [
            {
                "edgeHostnameId": "ehn_895822",
                "edgeHostnameDomain": "example.com.edgekey.net",
                "productId": "prd_Alta",
                "domainPrefix": "example.com",
                "domainSuffix": "edgekey.net",
                "status": "PENDING",
                "secure": true,
                "ipVersionBehavior": "IPV4"
            },
            {
                "edgeHostnameId": "ehn_887436",
                "edgeHostnameDomain": "example.com.edgesuite.net",
                "productId": "prd_Alta",
                "status": "ACTIVE",
                "domainPrefix": "www.mysales.co",
                "domainSuffix": "edgesuite.net",
                "secure": false,
                "ipVersionBehavior": "IPV4"
            }
        ]
    }
}

Sample POST Request:

{
    "productId": "prd_Alta",
    "domainPrefix": "custom.example.com",
    "domainSuffix": "edgesuite.net",
    "secure": false,
    "ipVersionBehavior": "IPV4"
}

EdgeHostname members

The top-level JSON object features the following outer contextual members:

• accountId
• contractId
• groupId

The edgeHostnames member is an object whose nested items array lists each edge hostname. These objects contain the following members:

To POST a new edge hostname, specify a single object containing productId, domainPrefix, and domainSuffix members, and optional ipVersionBehavior and secure members.

Property

Contains configuration data to apply to edge content. See the Properties interface for detailed interactions.

Sample GET response:

{
    "properties": {
        "items": [
            {
                "accountId": "act_1-1TJZFB",
                "contractId": "ctr_1-1TJZH5",
                "groupId": "grp_15225",
                "propertyId": "prp_175780",
                "propertyName": "example.com",
                "latestVersion": 2,
                "stagingVersion": 1,
                "productionVersion": null,
                "note": "Notes about example.com"
            }
        ]
    }
}

Sample POST request used to optionally clone an existing property:

{
    "productId"    : "prd_Obj_Caching",
    "propertyName" : "new.example.com"
    "cloneFrom": {
        "propertyId"    : "prp_175780",
        "version"       : 2,
        "copyHostnames" : true,
        "cloneFromVersionEtag" : "a9dfe78cf93090516bde891d009eaf57"
    }
}

Property members

The properties member within the top-level JSON is an object whose nested items array lists each property. These objects contain the following members:

Version

Specifies the version of a property. See the Property Versions interface for detailed interactions.

Sample GET response:

{
    "propertyId": "prp_173136",
    "propertyName": "981.calatog.amenai.net",
    "accountId": "act_1-1TJZFB",
    "contractId": "ctr_1-1TJZH5",
    "groupId": "grp_15225",
    "versions": {
        "items": [
            {
                "propertyVersion": 1,
                "updatedByUser": "afaden",
                "updatedDate": "2014-03-04T21:12:57Z",
                "productionStatus": "ACTIVE",
                "stagingStatus": "INACTIVE",
                "etag": "71573b922a87abc3",
                "productId": "prd_Alta",
                "ruleFormat": "latest",
                "note": "initial version"
            }
        ]
    }
}

Sample POST request:

{
    "createFromVersion": 2,
    "createFromVersionEtag": "5891b5b522d5df08"
}

Version members

The top-level JSON object features the following outer contextual members:

• accountId
• contractId
• groupId
• propertyId
• propertyName
• ruleFormat

The versions member is an object whose nested items array lists each version. These objects contain the following members:

Version POST members

When incrementing a new version, POST an object with the following members:

Hostname

Specifies an edge hostname that is applied to a property version. See the Property Version Hostnames interface for detailed interactions.

Sample GET response:

{
    "accountId": "act_1-1TJZFB",
    "contractId": "ctr_1-1TJZH5",
    "groupId": "grp_15225",
    "propertyId": "prp_175780",
    "propertyVersion": 1,
    "etag": "6aed418629b4e5c0",
    "hostnames": {
        "items": [
            {
                "cnameType": "EDGE_HOSTNAME",
                "edgeHostnameId": "ehn_895822",
                "cnameFrom": "example.com",
                "cnameTo": "example.com.edgesuite.net"
            },
            {
                "cnameType": "EDGE_HOSTNAME",
                "edgeHostnameId": "ehn_895833",
                "cnameFrom": "m.example.com",
                "cnameTo": "m.example.com.edgesuite.net"
            }
        ]
    }
}

Hostname members

The top-level JSON object features the following outer contextual members:

• accountId
• contractId
• groupId
• propertyId
• propertyVersion
• etag

The hostnames member is an object whose nested items array lists each hostname. These objects contain the following members:

Writing data to this resource requires that you PUT an array of all the hostname objects, each containing edgeHostnameId, cnameFrom, and cnameTo members.

Rule

Specifies the executable logic to apply to cached edge content. See the Property Version Rules interface for detailed interactions, and the Rule Trees section for guidance on how to structure the data.

Sample GET response:

{
    "accountId": "act_1-1TJZFB",
    "contractId": "ctr_1-1TJZH5",
    "groupId": "grp_15225",
    "propertyId": "prp_173136",
    "propertyVersion": 3,
    "etag": "a9dfe78cf93090516bde891d009eaf57",
    "ruleFormat": "v2015-08-08",
    "rules": {
        "name": "default",
        "options": {
            "is_secure": false
        },
        "criteria": [],
        "behaviors": [
            {
                "name": "origin",
                "options": {
                    "originType": "CUSTOMER",
                    "hostname": "origin.test.com",
                    "httpPort": 80,
                    "enableTrueClientIp": false,
                    "cacheKeyHostname": "ORIGIN_HOSTNAME",
                    "forwardHostHeader": "REQUEST_HOST_HEADER",
                    "compress": true
                }
            },
            {
                "name": "cpCode",
                "options": {
                    "value": {
                        "id": 12345,
                        "name": "main site"
                    }
                }

            }
        ],
        "children": []
    }
}

Rule members

The top-level JSON object features the following outer contextual members:

• accountId
• contractId
• etag
• groupId
• propertyId
• propertyVersion
• ruleFormat

The rules member defines the default rule object. A rule may apply behaviors based on an initial criteria test, and may also execute other nested rules, which are available as children. The entire data structure is called the rule tree. Each rule object contains the following members:

Activation

Activates property versions on a specific network. See the Property Activations interface for detailed interactions.

Sample GET response:

{
    "accountId": "act_1-1TJZFB",
    "contractId": "ctr_1-1TJZH5",
    "groupId": "grp_15225",
    "activations": {
        "items": [
            {
                "activationId": "atv_1696985",
                "propertyName": "example.com",
                "propertyId": "prp_173136",
                "propertyVersion": 1,
                "network": "STAGING",
                "activationType": "ACTIVATE",
                "status": "ACTIVE",
                "submitDate": "2014-03-05T02:22:12Z",
                "updateDate": "2014-03-04T21:12:57Z",
                "note": "Sample activation",
                "notifyEmails": [
                    "you@example.com",
                    "them@example.com"
                ]
            },
            {
                "activationId": "atv_1696986",
                "propertyName": "example.com",
                "propertyId": "prp_173136",
                "propertyVersion": 1,
                "network": "PRODUCTION",
                "activationType": "ACTIVATE",
                "status": "ACTIVE",
                "submitDate": "2014-03-02T02:22:12Z",
                "updateDate": "2014-03-01T21:12:57Z",
                "note": "Sample activation",
                "notifyEmails": [
                    "you@example.com",
                    "them@example.com"
                ]
            }
        ]
    }
}

Sample POST request:

{
    "propertyVersion": 3,
    "network": "STAGING",
    "note": "test of custom.example.com",
    "notifyEmails": [
        "you@example.com",
        "them@example.com"
    ]
}

Activation members

The top-level JSON object features the following outer contextual members:

• accountId
• contractId
• groupId

The activations member is an object whose nested items array lists each activation. These objects contain the following members:

RuleFormat

Lists available rule format versions. See List Rule Formats for a sample response.

The top-level ruleFormats member is an object whose nested items array lists each available rule format version string.

Schema

PAPI generates JSON schemas for various resources’ expected data format. For details on schemas you use to structure a rule tree, see Understanding Rule Formats, and the Get a Rule Format’s Schema operation for a sample request.

ClientSettings

Specifies default settings for an API client. See the Client Settings interface for a detailed interactions.

Sample GET response:

{
    "ruleFormat": "v2015-08-08"
}

ClientSettings members

The JSON object contains the following member:

Build

Provides details on the software build. See the Build interface for details.

Sample GET response:

{
    "catalogGitInfo": {
        "buildDate": "2014-05-26T23:56:21Z",
        "commitDate": "2014-05-26T23:55:53Z",
        "branch": "candidate-14.2",
        "commitId": "59a193acdf26ba6de1522486411a749f19efde8c"
    },
    "coreGitInfo": {
        "buildDate": "2014-04-25T17:02:43Z",
        "commitDate": "2014-04-25T17:01:11Z",
        "branch": "14.2",
        "commitId": "22163903cb91a62492dfce745aaa95de991b0653"
    },
    "currentCatalogVersion": "14.2.6",
    "coreVersion": "14.2"
}

Build members

The JSON object contains the following members:

Rule trees

A property’s main functionality is encapsulated in its set of rules. This section details how rules operate, and how to structure a rule tree from the root down. It shows how to inject variables within rules and modify their value at runtime. It also shows how to interpret contextual rule format JSON schemas that specify your product’s level of support for various behaviors and criteria.

The default rule

The JSON object for the API’s Rules interface features a top-level rules element that specifies a default rule object. As discussed in the Errors section, responses may also include top-level warnings, errors, and other contextual members, hence the additional layer of data. (The examples that follow remove extraneous data members.)

{
    "rules": {
        "name": "default",
        "options": {
            "is_secure": false
        }
    }
}

The rule’s default name is more than simply a default; the top-level rule must be named that way.

The only nominally mandatory member when saving a rule is its name, so you don’t have to pass in the options object, which as shown above displays default behavior. The Create a New Edge Hostname operation shows to specify hostnames as secure. When the property’s is_secure is set to true, it means you want to apply a shared certificate for all hostnames, possibly supplementing hostname-specific certificates. With is_secure enabled within the rule tree, you may receive warnings about any non-secure hostnames to which the rule applies. Note that some rule behaviors may only be available when is_secure is true.

Behaviors

The default rule must feature a set of behaviors, which is represented as an array of objects. New properties come with different sets of default rules depending on the product, but this much simpler example features the two behaviors that are always necessary to activate your property. The origin behavior determines how the edge network interacts with your origin servers, and the cpCode behavior is required for billing and reporting on traffic.

{
    "rules": {
        "name": "default",
        "options": {
            "is_secure": false
        },
        "behaviors": [
            {
                "name": "origin",
                "options": {
                    "originType": "CUSTOMER",
                    "hostname": "example.com",
                    "forwardHostHeader": "REQUEST_HOST_HEADER",
                    "cacheKeyHostname": "ORIGIN_HOSTNAME",
                    "compress": true,
                    "tcipEnabled": false,
                    "httpPort": 80
                }
            },
            {
                "name": "cpCode",
                "options": {
                    "value": {
                        "id": 12345,
                        "name": "main site"
                    }
                }
            }
        ]
    }
}

While nominally optional, default rules typically also specify a caching behavior to position the content on the edge, and a report behavior to refine the information you receive in traffic reports.

Each behavior object is identified by a name field. It features a locked member explained below, and most require a nested options object. Some behaviors only feature an enabled option that toggles whether the behavior is activated, while others require more fields once they’re activated. The exact set of options you need to specify for each behavior often varies depending on what you are trying to do, and some options are required based on the value of others. The PAPI Feature Catalog Reference details the requirements for each option.

In the origin example above, the originType is set to CUSTOMER, in which case your own server is the origin and you need to identify it with the hostname field. If the originType were set to any other value, the hostname would be unnecessary and thus ignored. PAPI silently ignores any unexpected values, but it always warns you about any expected values that are missing. (For example, setting the originType to NET_STORAGE would require another netStorage option providing details about your NetStorage account.)

Criteria

Rules are more powerful when they respond to the client request’s different criteria. To do so, the rule needs to specify children containing an array of nested rule objects. Along with a descriptive name, child rules may contain an additional set of criteria objects that determine when its behaviors execute.

In this example, the child rule’s contentType criteria matches requests for common HTML, CSS, and JavaScript files, and applies the gzipResponse behavior to compress them.

{
    "rules": {
        "name": "default",
        "options": {
            "is_secure": false
        },
        "behaviors": [
            {
                "name": "origin",
                "options": {
                    "originType": "CUSTOMER",
                    "hostname": "example.com",
                    "forwardHostHeader": "REQUEST_HOST_HEADER",
                    "cacheKeyHostname": "ORIGIN_HOSTNAME",
                    "compress": true,
                    "tcipEnabled": false,
                    "httpPort": 80
                }
            },
            {
                "name": "cpCode",
                "options": {
                    "value": {
                        "id": 12345,
                        "name": "main site"
                    }
                }
            }
        ],
        "children": [
            {
                "name": "Compress Text Content",
                "criteria": [
                    {
                        "name": "contentType",
                        "options": {
                            "matchOperator": "IS_ONE_OF",
                            "values": [
                                "text/html*",
                                "text/css*",
                                "application/x-javascript*"
                            ],
                            "matchWildcard": true,
                            "matchCaseSensitive": false
                        }
                    }
                ],
                "behaviors": [
                    {
                        "name": "gzipResponse",
                        "options": { "behavior": "ALWAYS" }
                    }
                ]
            }
        ]
    }
}

Criteria are structured exactly the same as behavior objects, with a name string identifier and a nested options object. Most criteria options behave similarly. The values option usually specifies the set of strings you are trying to match. (Throughout PAPI, whenever a value is optionally plural, it is always represented as an array.) Various matchWildcard options allow you to match flexibly with * and ? characters, and various matchCaseSensitive options allow you to ignore case. The matchOperator option typically allows you to invert the result, so that the criteria succeeds if specified values don’t match.

The example above features a single contentType criteria. Once you define more than one, the rule needs a criteriaMustSatisfy field to set whether to match any or all criteria. This alternate example of the children array adds a random criteria to match half the requests for the specified contentType.

"children": [
    {
        "name": "Compress Half of Requests for Text Content",
        "criteriaMustSatisfy": "all",
        "criteria": [
            {
                "name": "contentType",
                "options": {
                    "matchOperator": "IS_ONE_OF",
                    "values": [
                        "text/html*",
                        "text/css*",
                        "application/x-javascript*"
                    ],
                    "matchWildcard": true,
                    "matchCaseSensitive": false
                }
            },
            {
                "name": "random",
                "options": { "bucket": 50 }
            }
        ],
        "behaviors": [
            {
                "name": "gzipResponse",
                "options": { "behavior": "ALWAYS" }
            }
        ]
    }
]

In this example, criteriaMustSatisfy is set to all. If it were set to any, the criteria would compress all text content, and half of all other content, including images that are already compressed. (This is almost certainly not what you want, and exemplifies the sort of bug that falls beyond what the API can identify for you, as discussed in the Errors section.)

Note that rules do not provide any explicit support for else cases in response to criteria matches, but there are a couple of ways to implement them:

• Specify exclusive pairs of match criteria: From the example above, the first rule could specify a contentType criteria that matches HTML/CSS/JavaScript using a matchOperator of IS_ONE_OF. The second rule could specify the same contentType criteria, only with a matchOperator of IS_NOT_ONE_OF.

• Override a parent rule’s behavior: In the random example above, if you were to apply some other behavior to the remaining half of the requests, you would need to do so as part of the parent rule. If the parent rule enables a behavior that shouldn’t apply to the child, the child rule needs to specify the behavior again specifically to disable it.

Overall, the rules for how rules work are very simple. They are evaluated from top to bottom. A rule first evaluates its criteria, then executes its behaviors and children if the set of criteria matches. 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.

Based on the newly added custom hostname discussed in Create a New Edge Hostname, you would 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"
                }
            }
        }
    ]
}

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

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

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

If the API detects any problems with the data, they are noted as part of the response, and you 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.

Advanced and locked features

In addition to its name and component options, special types of behavior and criteria objects may feature these additional members:

• A uuid string signifies an advanced feature. Advanced behaviors and criteria are read-only, and can only be modified by Akamai representatives. They typically deploy metadata customized for you, whose functionality falls outside the predefined guidelines of what other read/write behaviors can do. Such metadata might also cause problems if executed outside of its intended context within the rule tree. (Advanced features are identified as read-only in the PAPI Feature Catalog Reference.)

• If a locked boolean member is true, it indicates a behavior or criteria that your Akamai representative has locked so that you can’t modify it. You typically arrange with your representative to lock certain behaviors to protect sensitive data from erroneous changes. Any kind of behavior or criteria may be locked, including writable ones.

When modifying rule trees, you must preserve the state of any uuid or locked members. You receive an error if you try to modify or delete either of these special types of feature. You can reposition regular features relative to these special ones, for example by inserting them within the same rule, but each rule’s sequence of special features must remain unchanged.

Additionally, rule objects may indicate the presence of special features:

• A uuid member present on a rule object indicates that at least one of its component behaviors or criteria is advanced and read-only. You need to preserve this uuid as well when modifying the rule tree.

• A criteriaLocked member enabled on a criteria rule by your Akamai representative means that you may not insert additional criteria objects within the sequence. This typically keeps complex logical tests from breaking. Preserve the state of criteriaLocked when modifying the rule tree.

Inserting variables

For many behavior and criteria option fields, you can inject variable text, custom values that interpret when the property executes at runtime. You can invoke a set of built-in variables to capture contextual information about the client’s request, define your own variables, assign values to them based on these built-in variables or various other inputs, and use transform functions to modify their value at any point throughout the rule tree. You can perform conditional logic based on the variable’s value, and catch any unforeseen runtime errors.

Variables allow you to implement functionality that previously was only possible by injecting advanced custom XML metadata, a process requiring assistance from your Technical Support representative. Variables may not completely replace advanced metadata functionality but can greatly reduce the need.

Throughout the PAPI Feature Catalog Reference, any option fields that allow you to inject variable text are marked allows variables. Within any of those option’s string values, you invoke variable names within pairs of {{ … }} delimiters. This example of a redirectPlus behavior option invokes the original request’s filename and concatenates it after a static string:

"destination": "/fixed/path/to/{{builtin.AK_FILENAME}}"

Note that, to accommodate the injection of variable strings, some options that reference conceptually numeric data are implemented instead as string types.

When inserting variables into text, you refer to them within a common namespace, in this case builtin for read-only system variables, followed by the unique variable name that is ultimately distributed in the XML metadata. The {{builtin.AK_FILENAME}} variable inserted above translates to %(AK_FILENAME) in XML metadata.

Built-in system variables

The following lists all the built-in system variables available to you. For any of these items that are optional, such as filename extensions, the inserted variable may yield a blank string. Note that the AKA prefix for the first variable listed varies from all others.

Declaring variables

While the built-in system variables described above are read-only, you can create and modify your own set of user variables. You can base their values on built-in system variables or other data about the request’s context, then transform them as described below.

First you need to declare the variable within the default rule’s variables array, otherwise you get an error when you later try to assign to them or invoke them in option values. The example below defines a single variable whose unique underlying name is VAR_NAME. Variable names may only feature alphanumeric and underscore characters. Uppercase is recommended by convention but is not required.

{
    "rules": {
        "name": "default",
        "options": {
            "is_secure": false
        },
        "variables": [
            {
                "name": "VAR_NAME",
                "value": "default value",
                "description": "This is a sample Property Manager variable.",
                "hidden": false,
                "sensitive": false
            }
        ],
        "criteriaMustSatisfy": "all",
        "criteria": [],
        "behaviors": [],
        "children": []
    }
}

The variable declaration object specifies these members:

There are three different ways variable names appear:

• Within the variables declaration, you specify the base VAR_NAME.

• When you modify the variable with setVariable or match it with matchVariable as described below, you add a PMUSER_ prefix to refer to the variable name as PMUSER_VAR_NAME. (In activated metadata, this appears as %(PMUSER_VAR_NAME).)

• When you insert the variable as an expression within behavior and criteria option fields, you need an additional user. namespace prefix: {{user.PMUSER_VAR_NAME}}.

Assigning variables

Once you declare a variable within the default rule’s variables array, you assign a value to it using the setVariable behavior, which you can place anywhere as appropriate within the rule tree. This example assigns the value of the built-in AK_EXTENSION variable to store the request’s file extension in a user variable named EXT. To assign a variable, specify the variableName you want to modify, specify the valueSource as EXPRESSION, then as the variableValue inject the variable using the same syntax as in any other option field. In this example, setting the TRANSFORM to NONE means you don’t yet want to change the value.

{
    "name": "setVariable",
    "options": {
        "variableName": "PMUSER_EXT",
        "valueSource": "EXPRESSION",
        "variableValue": "{{builtin.AK_EXTENSION}}",
        "transform": "NONE"
    }
}

The matchVariable criteria allows you to test a variable’s value at runtime. This example set of criteria tests if the request is for a filename with no extension, but requiring a filename and thus excluding any directory-style URLs that end with a slash character:

"criteriaMustSatisfy": "all",
"criteria": [
  {
    "name": "matchVariable",
    "options": {
      "variableName": "AK_FILENAME",
      "mode": "IS_NOT_EMPTY"
    }
  },
  {
    "name": "matchVariable",
    "options": {
      "variableName": "PMUSER_EXT",
      "mode": "IS_EMPTY"
    }
  }
]

NOTE: While the matchVariable criteria offers a way to account for known error scenarios, see the Debugging section for more information on the variableError criteria, which allows you to detect other unforeseen error scenarios that only reveal themselves at runtime.

In response to the test criteria above, one of the rule’s accompanying behaviors may assign a static EXPRESSION of html for use as a default file extension:

{
    "name": "setVariable",
    "options": {
        "variableName": "PMUSER_EXT",
        "valueSource": "EXPRESSION",
        "variableValue": "html",
        "transform": "NONE"
    }
}

You can assign values from many other sources besides built-in system variables. Setting the setVariable behavior’s valueSource to EXTRACT gives you the option to assign more specific values from the request. The extractLocation may specify header, cookie, and query parameter names, certificates, path directory components, and any embedded path parameters. Setting extractLocation to EDGESCAPE allows you to leverage a great deal of location-based data based on this request. The sample behaviors below assign the client request’s geographic location to a pair of LAT and LONG variables.

{
    "name": "setVariable",
    "options": {
        "variableName": "PMUSER_LAT",
        "valueSource": "EXTRACT",
        "extractLocation": "EDGESCAPE",
        "locationId": "LAT",
        "transform": "NONE"
    }
},
{
    "name": "setVariable",
    "options": {
        "variableName": "PMUSER_LONG",
        "valueSource": "EXTRACT",
        "extractLocation": "EDGESCAPE",
        "locationId": "LONG",
        "transform": "NONE"
    }
}

In addition, when the valueSource is set to GENERATE, you can incorporate various random numbers and hex strings into variables. See the setVariable behavior for details on all the sources of information you can assign to variables.

Modifying variables

In all of the examples above, the transform option is set to NONE, which leaves the value unchanged after assigning it, but it supports a large set of functions that in effect offers an embedded programming language. Transform functions allow you to:

• do basic arithmetic
• perform bitwise operations
• convert case
• locate and generate substrings
• make regular expression substitutions
• perform many conversions and encodings

See the setVariable behavior for comprehensive details.

To modify a value within any setVariable behavior, set its transform function along with any necessary dependencies. Each behavior can only transform its value once, so to transform a value more than once you need to form a chain of setVariable behaviors. Each subsequent behavior must reassign the transformed value back to itself, then perform an additional transformation.

This simple example modifies a LANG user variable, assigning it the value of the request’s Accept-Language header. The initial behavior performs a SUBSTRING transform to limit the string to the initial two-letter code. The second behavior reassigns {{user.PMUSER_LANG}} back into LANG, then runs the UPPER transform to convert to uppercase.

{
    "name": "setVariable",
    "options": {
        "variableName": "PMUSER_LANG",
        "valueSource": "EXTRACT",
        "extractLocation": "CLIENT_REQUEST_HEADER",
        "headerName": "Accept-Language",
        "transform": "SUBSTRING",
        "startIndex": "1",
        "endIndex": "2"
    }
},
{
    "name": "setVariable",
    "options": {
        "variableName": "PMUSER_LANG",
        "valueSource": "EXPRESSION",
        "variableValue": "{{user.PMUSER_LANG}}",
        "transform": "UPPER"
    }
}

For more details on how to use variables within the Property Manager portal, see Variables.

Understanding rule formats

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 the example above does not display. The toprule itself specifies an object that must feature 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.

NOTE: 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 via add-on modules, as discussed in PAPI Concepts. To determine the set of features currently available on your account, saving a property that specifies them returns an error that notifies you otherwise.

The following 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": {
                    "enum": [ "max-age", "no-store", "bypass-cache", "both", "cc", "expires" ],
                    "default": "max-age"
                },
                "mustRevalidate": {
                    "enum": [ "off", "on" ],
                    "default": "off"
                },
                "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 is not necessarily available within the schema, and may be implemented as part of the API’s back end. The rule format also does not 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 PAPI Feature Catalog Reference details 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 the following to represent a CP code object with a required id member:

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

The rule format does not specify the name member that also typically appears within a cpcode object. It does not 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.

Errors

This section shows you how to handle various kinds of error responses the Property Manager API generates. In addition to standard HTTP error responses, it discusses how to resolve errors reported in rule trees before you activate a property, and how to deal with errors from variables as they are interpreted on the edge once you activate a property. This section also lists the range of HTTP response codes, provides details for many API-specific error messages along with their likely causes, and reports any known issues remaining in the current API release.

Known issues

The following known issues may affect your ability to use the Property Manager API:

• Large rule trees that take more than 5 minutes to validate may time out with a 500 error. As a workaround, try to create smaller configurations targeting smaller sets of hostnames. The less executable logic each configuration contains, the less time it takes to validate it.

• If you associate PAPI credentials with a user who has access to more than one portal account, attempts to create edge hostnames result in authorization errors.

• If you create a property within Property Manager with an empty set of hostnames, a GET request to Property Version Hostnames results in a 500 error.

• Some streaming media configurations are not supported. PAPI supports all properties supported by Property Manager.

• Before using PAPI, any properties that use the older Configuration Manager must first be upgraded to the Property Manager within Control Center.

JSON problems

API endpoints routinely respond with failure codes to a wide range of problems with the integrity of the data you are trying to modify, everything from malformed JSON, to missing fields, to mismatching etags digests. The API returns these error responses in the standard JSON Problem format.

PAPI also serializes problems in some success responses. PAPI allows you to succeed in saving property rule or hostname data in a state that would later fail on activation, but by default it embeds guidance about each problem within the response. Two kinds of problem appear in success responses:

• An errors array notes any problem that would prevent activation. You need to fix these before activating the property.

• A warnings array notes less severe issues. You can either modify the data in response, or acknowledge the set of warnings when later activating the property.

For example, when you try to PUT a rule tree that’s missing required origin and cpCode behaviors, a 200 response identifies them as errors:

{
    "accountId": "act_1-1TJZFB",
    "contractId": "ctr_1-1TJZH5",
    "groupId": "grp_15225",
    "propertyId": "prp_173136",
    "propertyVersion": 3,
    "etag": "a9dfe78cf93090516bde891d009eaf57",
    "errors": [
        {
            "type": "/papi/v0/errors/validation.required_behavior",
            "title": "Missing required behavior in default rule",
            "detail": "In order for this property to work correctly behavior Content Provider Code needs to be present in the default section",
            "instance": "/papi/v0/properties/prp_173136/versions/3/rules#err_100",
            "behaviorName": "cpCode"
        },
        {
            "type": "/papi/v0/errors/validation.required_behavior",
            "title": "Missing required behavior in default rule",
            "detail": "In order for this property to work correctly behavior Origin needs to be present in the default section",
            "instance": "/papi/v0/properties/prp_173136/versions/3/rules#err_101",
            "behaviorName": "origin"
        }
    ],
    "rules": {
        "name": "default",
        "options": {
            "is_secure": false
        },
        "children": [
            {
                "name": "Handle /my-path",
                "criteriaMustSatisfy": "all",
                "criteria": [
                    {
                        "name": "wildcard",
                        "value": ["/my-path"]
                    }
                ],
                "behaviors": [
                    {
                        "name": "caching",
                        "behavior": "MAX_AGE",
                        "ttl": "1m"
                    }
                ]
            }
        ]
    }
}

Even though you can save the rule tree, you can’t activate the property until you add the missing behaviors. (See the Rule Trees section for guidance on how to structure rule trees.)

PAPI also allows you the option to skip potentially lengthy validation tests that would result in these errors and warnings. You would still need to address the problems prior to activation, but this option allows you to modify and save data more quickly as a matter of routine throughout your development cycle. See Validation and Activation Time for more information.

Debugging rule trees

The API may release a wide range of validation errors based on the content of rule trees, many of which are detailed below. A few unusual error scenarios are unique to PAPI:

• As discussed in the Resources section, you can freeze the API to use a specific set of behavior and criteria versions. If instead you specify the rule format that uses the latest versions, behaviors and criteria silently update, and may produce errors if their validation requirements change. Other validation errors may remain even when properly updating from one rule format version to another.

• As discussed in the Rules section, some behaviors and criteria are locked and read-only, and can only be modified with assistance from Akamai Professional Services. You get an error if you try to modify or move them elsewhere within the rule tree.

• As discussed in the Rule Trees section and detailed in the PAPI Feature Catalog Reference, some options may be required depending on the values of others. It is much easier to accidentally omit necessary values in the API than in Control Center.

• Some errors may reference Schema objects, which you can examine to determine each product’s support for behaviors and criteria. They also list the full set of options for each, along with their expected data types. However, schemas do not represent dependencies among options.

Aside from errors, PAPI more often returns a set of warnings after checking your chosen set of behaviors and criteria for identifiable logical inconsistencies. Here is a typical warning, whose errorLocation is a URL fragment that can be interpreted as a JSON Pointer expression to help you locate the problem within the JSON tree you submitted:

"warnings": [
    {
        "type": "https://problems.luna.akamaiapis.net/papi/v0/validation/need_feature",
        "errorLocation": "#/rules/behaviors/5",
        "detail": "`Tiered Distribution` only applies to cacheable
              content, but caching was never turned on."
    }
]

Behaviors such as tieredDistribution and prefreshCache can only operate on cached content on edge servers, so the warning identifies when the caching behavior is not enabled. As another example, the cacheKeyIgnoreCase behavior allows requests for files and query parameters with mixed upper- and lower-case letters to resolve to the same cache key. If you pair that behavior with a criteria that doesn’t also specify a case-insensitive match, the warning alerts you not to apply different behaviors to the same cached object based on random variations in case among incoming requests.

These warnings often identify obvious logical problems, such as exclusive sets of criteria when criteriaMustSatisfy is set to all, or nested criteria that can never execute because they’re logically exclusive with their ancestor rules’ criteria. However, as in all programming environments, no validation mechanism can identify all potential bugs, so you need to carefully step through the code. You can also request text/xml rather than application/json from the Property Versions interface if you would rather look at how a version’s combined set of rules and hostnames translate to the Akamai metadata that is ultimately distributed to edge servers. Contact your Akamai Professional Services representative if you need to better understand the metadata.

NOTE: Like Control Center, the API may require you to acknowledge each warning before you activate a property. Unlike Control Center, you can batch-acknowledge all warnings by setting acknowledgeAllWarnings to true on the new activation. Either way, pay careful attention to any warnings you have received before you activate a property version, or your site can experience serious problems.

Debugging variables

Most problems with rule trees are detected prior to activation, but problems with variables often occur only at runtime, and are thus more challenging to debug.

The most useful way to debug variables is to view their values in session-related response headers for test content on the staging network:

1. As discussed in the section on Declaring Variables, each variable defined in the default rule features two hidden and sensitive options, and you first need to disable both for any variables you want to inspect.

2. Activate the property that includes the variables on the staging network.

3. Once content activates, send a Pragma:akamai-x-get-extracted-values header in your test requests. The response includes X-Akamai-Session-Info headers that reflect the value of each declared variable.

4. After debugging, re-enable the hidden and sensitive options if necessary before activating to the production network.

Logging variables in session response headers allows you to check their final values after the rule tree executes. To specifically respond to errors as they occur within the rule tree, you can apply variableError criteria as part of a debugging rule after any setVariable that may cause a problem. For example, if you set user variables that extract the contents of a specific header or cookie name, an error results if either item is missing from the request. The following criteria test executes if any errors occur for the specified set of variables:

{
    "name" : "variableError",
    "options" : {
        "variableNames" : "CUSTOM_HEADER CUSTOM_COOKIE"
    }
}

This approach does not allow you to report on the specific error, but you can still fashion appropriate behaviors, especially for use in testing on the staging network. For example, this denies the request and responds with an appropriate error:

{
    "name" : "denyAccess",
    "options" : {
        "enabled" : true,
        "reason" : "missing-required-header-or-cookie"
    }
}

For more details on how variables work within rule trees, see Assigning Variables, or Variables. within the Property Manager portal.

JSON request schema

Errors about malformed data typically reference schema objects that describe whichever resource you are trying to interact with. PAPI provides a separate Request Schema interface for these objects that reference specific schema files. For example, the following describes the expected data structure when creating a new edge hostname:

GET /papi/v0/schemas/request/EdgeHostnamesPostRequestV0.json

HTTP success codes

The API produces the following range of HTTP success codes:

The tables below provide details for many of the errors you may encounter, along with the HTTP status codes they share. (Note that this is not an exhaustive listing, and excludes problems relating to rule trees.) Each problem object’s type member corresponds to items listed in the tables below. Problem types reported in HTTP error responses follow this URL pattern, where the type identifier may include an additional slash character:

https://problems.luna.akamaiapis.net/papi/{version}/{type}

URLs for many problem types included within rule tree and property hostname response objects are formed with an additional validation component:

https://problems.luna.akamaiapis.net/papi/{version}/validation/{type}

HTTP errors

Data errors

Edge hostname errors

Property hostname errors

An additional set of errors may be listed within Hostname objects that prevent you from activating the property version:

Property errors

Activation errors

Behavior/criteria errors

These general errors relate to how you implement behaviors and criteria. They may be listed within Rule objects, and may prevent you from activating the property version:

Option value errors

These errors may be listed within Rule objects, and may prevent you from activating the property version:

Variable-related errors

These errors may be listed within Rule objects, and may prevent you from activating the property version:

Metadata errors

These errors may be listed within Rule objects, and may prevent you from activating the property version:

Contract, account, and CP code errors

These errors may be listed within Rule or Hostname objects, and may prevent you from activating the property version:

Criteria-specific errors

These errors relate to how specific match criteria execute. They may be listed within Rule objects, and may prevent you from activating the property version.