Property Manager API v0 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:

Member Type Description
accountId String A unique identifier for the prevailing account.
accountName String A descriptive name for the account.
contractId String A unique identifier for the prevailing contract.
groupId String A unique identifier for the prevailing group.
etag String A digest with which to check the data’s integrity.
propertyId String A unique identifier for the property.
propertyVersion Number Identifies a property instance.
propertyName String A descriptive name for the property.
ruleFormat String A read-only value that indicates the versioned set of features and criteria that are currently applied to a rule tree.

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:

Member Type Description
Required
groupId String A unique identifier for the group.
groupName String A descriptive label for the group.
contractIds Array A set of string identifiers for contracts whose products can be applied to properties within a group.
Optional
parentGroupId String Identifies another group as a parent, defining the relative location of the group within the group hierarchy. If omitted, it is the root-level group at the top of the hierarchy.

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:

Member Type Description
Required
contractId String A unique identifier for the contract.
contractTypeName Enumeration Distinguishes the type of contract, either Direct Customer or Indirect Customer.

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:

Member Type Description
Required
productId String A unique identifier for the product.
productName String A descriptive name for the product.

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:

Member Type Description
Required
cpcodeName String A descriptive label for the CP code.
productId String On POST, the product to assign to this CP code.
Optional
cpcodeId String A unique identifier for the CP code.
createdDate String A time stamp for the CP code.
productIds Array On GET, lists identifiers for products assigned to this CP code. (Note that PAPI does not support Property Manager’s ability to assign more than one product to a CP code.)

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:

Member Type Description
Required
domainPrefix String The origin domain portion of the edge hostname. An edge hostname consists of a customer-specific namePrefix such as www.example.com and an Akamai-specific domainSuffix such as edgesuite.net. The edge hostname’s final DNS CNAME combines the two, for example, www.example.com.edgesuite.net.
domainSuffix String The Akamai-specific portion of the edge hostname, for example, edgesuite.net.
productId String The product associated with the edge hostname.
Optional
edgeHostnameDomain String The full edge domain name formed from the domainPrefix and domainSuffix.
edgeHostnameId String The edge hostname’s unique identifier, which can be assigned to a property.
ipVersionBehavior Enumeration Which version of the IP protocol to use: IPV4 for version 4 only, or IPV6_COMPLIANCE for both 4 and 6. The default value for requests is IPV4.
secure Boolean Set to true if the edge hostname is to be used with SSL. The default value for POST requests is false. (Setting secure:true for new edge hostnames is not supported.)
status Enumeration Either active for fully deployed, or pending for a newly defined hostname whose DNS mapping has not yet been distributed across the entire Akamai network. (Not to be confused with a property activation’s deployment status.)

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:

Member Type Description
Required
propertyId String The property’s unique identifier.
propertyName String A descriptive name for the property.
Optional
contractId String Identifies the contract under which the property was created.
groupId String Identifies the group to which the property is assigned.
productId String The product assigned to the property, required when POSTing a new property.
accountId String Identifies the account under which the property was created.
cloneFrom Property.cloneFrom Optionally identifies another property instance to clone when making a POST request to create a new property. The cloned property must share the same contract and group.
latestVersion Number Specifies the most recent version of the property.
note String Further descriptive commentary.
productionVersion Number The most recent version to be activated to the production network, otherwise null.
stagingVersion Number The most recent version to be activated to the test network, otherwise null.

Property.cloneFrom

To POST a new property, specify an object with the required productId and propertyName members. The optional cloneFrom member specifies an object with the following members:

Member Type Description
Required
propertyId String Specifies the property to clone.
version Number Specifies the version of the property to clone.
Optional
cloneFromVersionEtag String Performs an etag data integrity check on the original property.
copyHostnames Boolean Assigns the same set of hostnames to the new property, false by default.

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:

Member Type Description
Required
note String A descriptive log comment.
productId String The product assigned to the property when versioned.
productionStatus Enumeration Whether the version has been activated to the production network. (If ACTIVE, the version is read-only. Otherwise it may be INACTIVE or PENDING.)
propertyVersion Number A positive integer identifying the incremental version.
stagingStatus Enumeration Whether the version has been activated to the test network. (If ACTIVE, the version is read-only. Otherwise it may be INACTIVE or PENDING.)
updatedByUser String The username associated with the new version.
updatedDate String The date stamp of the version’s latest update.
Optional
etag String A digest with which to check the data’s integrity.
Optional, only when included in search results
accountId String Identifies the account under which the property version is active.
contractId String Identifies the contract under which the property version is active.
edgeHostname String When searching for hostname or edgeHostname, this shows the edge hostname to which the active version currently applies.
groupId String Identifies the group under which the property version is active.
hostname String When searching for hostname or edgeHostname, this shows the property hostname to which the active version currently applies.
propertyId String Identifies the property to which the listed version belongs.
propertyName String The name of the property to which the listed version belongs.

Version POST Members

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

Member Type Description
Required
createFromVersion Number The property version on which to base the new version.
Optional
createFromVersionEtag String The data digest of the version on which to base the new version.

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:

Member Type Description
Required
cnameFrom String The original origin’s hostname.
cnameType Enumeration Only one supported EDGE_HOSTNAME value.
edgeHostnameId String A unique identifier for the edge hostname.
Optional
cnameTo String The hostname for edge content, corresponding to the edge hostname object’s edgeHostnameDomain member.

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 Rules 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:

Member Type Description
Required
behaviors Array A series of behavior objects. Optional on nested rules.
name String A description of the rule. The top-level rule must be named default.
Optional
children Array A series of nested rule objects, which execute after the current rule’s criteria and behaviors.
comment String A descriptive comment to help you track the rule’s function.
criteriaLocked Boolean Within child rules, this prohibits any modifications to criteria objects. This value is read-only. Contact your Akamai representative to change it.
criteria Array A series of criteria objects.
options Rule.option Flags that apply to the top-level rule object.

Rule.options

Member Type Description
Optional
is_secure Boolean When enabled, serves the property’s content over SSL. Doing so may enable additional rule behaviors.

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:

Member Type Description
Required
propertyVersion Number The property version targeted with activation. Once activated, you can no longer modify that version of the property.
network Enumeration The network to activate on, either STAGING or PRODUCTION.
notifyEmails Array A list of email address strings to notify when the activation status changes.
Optional
acknowledgeWarnings Array A list of msg_-prefixed strings acknowledging any warnings noted when modifying rules, or in responses to previous activation requests.
acknowledgeAllWarnings Boolean Whether you need to acknowledge each warning as an acknowledgeWarnings array.
activationId String The activation’s unique identifier.
activationType Enumeration Either ACTIVATE or DEACTIVATE. The default is ACTIVATE. Any new activation automatically deactivates the current activation. Note that if you were to POST a DEACTIVATE type on an active property, it would no longer serve any traffic. You would need to modify (de-Akamaize) your DNS configuration and specify a different way to field the traffic.
fastPush Boolean Enable a fast meta-data push when activating a new property, true by default.
ignoreHttpErrors Boolean Ignore any HTTP errors when pushing fast meta-data activation, true by default.
note String Assigns a log message to the activation request.
propertyId String Identifies property targeted with activation.
propertyName String The name of the property targeted with activation.
status Enumeration Either ACTIVE, INACTIVE, PENDING, ZONE_1, ZONE_2, ZONE_3, ABORTED, FAILED, DEACTIVATED, PENDING_DEACTIVATION, or NEW.
submitDate String A date stamp marking when the activation initiated.
updateDate String A date stamp marking when the status last changed.

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:

Member Type Description
Required
ruleFormat String A string key indicating the dated version of the API’s set of features specified by a rule format schema.

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:

Member Type Description
Required
coreVersion String The Property Manager version.
currentCatalogVersion String The version of the Property Manager catalog that specifies rule behaviors and criteria. Note that this catalog is not the same as the rule format version available in the Rule Format Versions interface.
catalogGitInfo Object Specifies internal tracking data listed below.
coreGitInfo Object Specifies internal tracking data listed below.

Build.*GitInfo

Member Type Description
Required
branch String The name of the build’s branch.
buildDate String When the code was built.
commitDate String When the final commit occurred.
commitId String An opaque data signature for the final commit.

Last modified: 6/7/2017