
- Overview
- Resources
- API summary
- List groups
- List contracts
- List products
- List CP codes
- Create a new CP code
- Get a CP code
- List edge hostnames
- Create a new edge hostname
- Get an edge hostname
- List properties
- Create or clone a property
- Get a property
- Remove a property
- List versions
- Create a new version
- Get a version
- Get the latest version
- List available behaviors
- List available criteria
- List property hostnames
- Update property hostnames
- Get a rule tree
- Get a digest for a rule tree
- Update a rule tree
- Search properties
- List activations
- Activate a property
- Get an activation
- Cancel a pending activation
- List rule formats
- Get a request schema
- Get a rule format schema
- Get client settings
- Update client settings
- Get build details
- Data
- Rule trees
- Errors
- Known issues
- JSON problems
- Debugging rule trees
- Debugging variables
- JSON request schema
- HTTP success codes
- HTTP errors
- Data errors
- Edge hostname errors
- Property hostname errors
- Property errors
- Activation errors
- Behavior/criteria errors
- Option value errors
- Variable-related errors
- Metadata errors
- Contract, account, and CP code errors
- Criteria-specific errors
- Behavior-specific errors
- Other errors
Property Manager API v0
The original beta version of PAPI.
Learn more:
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.
Get started
Before using PAPI for the first time:
Contact your Akamai representative to enable it for your account.
Review Get Started with APIs for details on how to set up client tokens to access any Akamai API. These tokens appear as custom hostnames that look like this:
https://akzz-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX.luna.akamaiapis.net
.To enable this API, choose the API service named Property Manager (PAPI), and set the access level to READ-WRITE.
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.
If using tools such as
edgegrid-curl
andedgegrid-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 settingmax-body:131072
in the.egcurl
file, or in python by passing inmax_body:131072
as part of theEdgeGridAuth()
call.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!
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 anenabled
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
andm.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 oredgekey.net
over secure HTTPS. For example, your source hostnamem.example.com
corresponds by default to the edge hostnamem.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:
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 thanversion
.
PAPI applies the following JSON member naming conventions:
*Name
members are meant to be descriptive and human-readable (such aspropertyName
), and never need to appear as input to an endpoint.*Id
members are machine-readable identifiers (such aspropertyId
) often used as inputs to endpoints. The values of*Id
members use the following type prefixes to help distinguish them:act_
prefix foraccountId
ctr_
prefix forcontractId
grp_
prefix forgroupId
prd_
prefix forproductId
prp_
prefix forpropertyId
ehn_
prefix foredgeHostnameId
hst_
prefix forhostnameId
atv_
prefix foractivationId
msg_
prefix formessageId
cpc_
prefix forcpcodeId
*Date
members represent date-time in ISO 8601 format using UTC timezone (such asupdateDate
). The API names all timestamps as*Date
, they all use this same format.*Link
members are URLs (such asactivationLink
) 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 thanhttps://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 theLocation
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
orIf-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 theIf-Match
HTTP header when writing property hostnames, because that interface specifies an array, which can’t accommodate a top-leveletags
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 anetag
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 anetag
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 tofalse
.When running the Update a Property’s Hostnames operation, set the
validateHostnames
query parameter tofalse
.
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
Operation | Method | Endpoint |
---|---|---|
Groups | ||
List Groups | GET | /papi/ |
Contracts | ||
List Contracts | GET | /papi/ |
Products | ||
List Products | GET | /papi/ |
CP Codes | ||
List CP Codes | GET | /papi/ |
Create a New CP Code | POST | /papi/ |
Get a CP Code | GET | /papi/ |
Edge Hostnames | ||
List Edge Hostnames | GET | /papi/ |
Create a New Edge Hostname | POST | /papi/ |
Get an Edge Hostname | GET | /papi/ |
Properties | ||
List Properties | GET | /papi/ |
Create or Clone a Property | POST | /papi/ |
Get a Property | GET | /papi/ |
Remove a Property | DELETE | /papi/ |
Property Versions | ||
List Versions | GET | /papi/ |
Create a New Version | POST | /papi/ |
Get a Version | GET | /papi/ |
Get the Latest Version | GET | /papi/ |
List Available Behaviors | GET | /papi/ |
List Available Criteria | GET | /papi/ |
Property Version Hostnames | ||
List a Property’s Hostnames | GET | /papi/ |
Update a Property’s Hostnames | PUT | /papi/ |
Property Version Rules | ||
Get a Rule Tree | GET | /papi/ |
Get a Rule Tree’s Digest | HEAD | /papi/ |
Update a Rule Tree | PUT | /papi/ |
Property Search | ||
Search Properties | GET | /papi/ |
Property Activations | ||
List Activations | GET | /papi/ |
Activate a Property | POST | /papi/ |
Get an Activation | GET | /papi/ |
Cancel a Pending Activation | DELETE | /papi/ |
Rule Formats | ||
List Rule Formats | GET | /papi/ |
Schemas | ||
Get a Request’s Schema | GET | /papi/ |
Get a Rule Format’s Schema | GET | /papi/ |
Client Settings | ||
Get Client Settings | GET | /papi/ |
Update Client Settings | PUT | /papi/ |
Build | ||
Get Build Details | GET | /papi/ |
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.
GET /papi/
Status 200 application/json
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" ]
},
{
"groupName": "TomTest",
"groupId": "grp_41443",
"parentGroupId": "grp_15225",
"contractIds": [ "ctr_1-1TJZH5" ]
}
]
}
}
GET a list of groups from
/papi/v0/groups/
.Select the appropriate group object from the JSON’s
groups.items
array.Store the object’s
grp_
-prefixedgroupId
.
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.
GET /papi/
Status 200 application/json
Response:
{
"accountId": "act_1-1TJZFB",
"contracts": {
"items": [
{
"contractId": "ctr_1-1TJZH5",
"contractTypeName": "Direct Customer"
}
]
}
}
GET the list of contracts from
/papi/v0/contracts/
.Select the appropriate contract object from the JSON’s
contracts.items
array.Store the object’s
ctr_
-prefixedcontractId
.
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.
GET /papi/
Example: /papi/
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
contractId |
String | ctr_1-1TJZH5 |
Unique identifier for the contract. Remove the ctr_ prefix if using the value in other Akamai APIs. |
Status 200 application/json
Response:
{
"accountId": "act_1-1TJZFB",
"contractId": "ctr_1-1TJZH5",
"products": {
"items": [
{
"productName": "Alta",
"productId": "prd_Alta"
}
]
}
}
List Contracts from
/papi/v0/contracts
and store the relevantcontractId
.GET a list of products from
/papi/v0/products/{?contractId}
Select the appropriate product object from the JSON’s
products.items
array.Store the object’s
prd_
-prefixedproductId
.
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.
GET /papi/
Example: /papi/
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
contractId |
String | ctr_1-1TJZFW |
Unique identifier for the contract. Remove the ctr_ prefix if using the value in other Akamai APIs. |
groupId |
String | grp_15166 |
Unique identifier for the group. Remove the grp_ prefix if using the value in other Akamai APIs. |
Status 200 application/json
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"
}
]
}
}
List Contracts from
/papi/v0/contracts
and store the relevantcontractId
.List Groups from
/papi/v0/groups
and store the relevantgroupId
.List CP codes from
/papi/v0/cpcodes/{?contractId,groupId}
.Select the appropriate CpCode object from the JSON’s
cpcodes.items
array.Store the object’s
cpc_
-prefixedcpcodeId
.
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.
POST /papi/
Example: /papi/
Content-Type: application/json
Request:
{
"productId": "prd_Web_App_Accel",
"cpcodeName": "SME WAA"
}
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
contractId |
String | ctr_1-1TJZFW |
Unique identifier for the contract. Remove the ctr_ prefix if using the value in other Akamai APIs. |
groupId |
String | grp_15166 |
Unique identifier for the group. Remove the grp_ prefix if using the value in other Akamai APIs. |
Status 201 application/json
Headers:
Location: /papi/v0/cpcodes/cpc_33190?contractId=ctr_1-1TJZFW&groupId=grp_15166
Response:
{
"cpcodeLink": "/papi/v0/cpcodes/cpc_33190?contractId=ctr_1-1TJZFW&groupId=grp_15166"
}
List Contracts from
/papi/v0/contracts
and store the relevantcontractId
.List Groups from
/papi/v0/groups
and store the relevantgroupId
.List Products from
/papi/v0/products{?contractId}
and store the relevantproductId
with which to enable the CP code.Build a CpCode POST object.
POST the object to
/papi/v0/cpcodes/{?contractId,groupId}
.Optionally GET the new CP code from the response’s
cpcodeLink
orLocation
header.
Get a CP code
This operation gets details about a CP code.
GET /papi/
Example: /papi/
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
contractId |
String | ctr_1-1TJZFW |
Unique identifier for the contract. Remove the ctr_ prefix if using the value in other Akamai APIs. |
cpcodeId |
String | cpc_33190 |
Unique identifier for the CP code. Remove the cpc_ prefix if using the value in other Akamai APIs. |
groupId |
String | grp_15166 |
Unique identifier for the group. Remove the grp_ prefix if using the value in other Akamai APIs. |
Status 200 application/json
Response:
{
"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 Contracts from
/papi/v0/contracts
and store the relevantcontractId
.List Groups from
/papi/v0/groups
and store the relevantgroupId
.List CP Codes from
/papi/v0/cpcodes/{?contractId,groupId}
and store the relevantcpcodeId
.GET the CP code from
/papi/v0/cpcodes/{cpcodeId}{?contractId,groupId}
.Store the object’s
cpc_
-prefixedcpcodeId
.
List edge hostnames
This lists all edge hostnames available under a contract. You assign these hostnames to a property as a separate operation.
GET /papi/
Example: /papi/
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
contractId |
String | ctr_1-1TJZH5 |
Unique identifier for the contract. Remove the ctr_ prefix if using the value in other Akamai APIs. |
groupId |
String | grp_15255 |
Unique identifier for the group. Remove the grp_ prefix if using the value in other Akamai APIs. |
Optional | |||
options |
String | mapDetails |
Comma-separated list of options to enable; mapDetails enables extra mapping-related information. |
Status 200 application/json
Headers:
X-Limit-Edgehostnames-Per-Contract-Limit: 100
X-Limit-Edgehostnames-Per-Contract-Remaining: 98
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",
"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"
}
]
}
}
List Contracts from
/papi/v0/contracts
and store the relevantcontractId
.List Groups from
/papi/v0/groups
and store the relevantgroupId
.GET the edge hostname list from
/papi/v0/edgehostnames/{?contractId,groupId}
EdgeHostname objects are listed within the response’s
edgeHostnames.items
array.
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.
POST /papi/
Example: /papi/
Content-Type: application/json
Request:
{
"productId": "prd_PPP",
"domainPrefix": "www.example.com",
"domainSuffix": "edgesuite.net",
"secure": true,
"ipVersionBehavior": "IPV4",
"slotNumber": 12345
}
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
contractId |
String | ctr_1-1TJZH5 |
Unique identifier for the contract. Remove the ctr_ prefix if using the value in other Akamai APIs. |
groupId |
String | grp_15255 |
Unique identifier for the group. Remove the grp_ prefix if using the value in other Akamai APIs. |
Optional | |||
options |
String | mapDetails |
Comma-separated list of options to enable; mapDetails enables extra mapping-related information. |
Status 201 application/json
Headers:
Location: /papi/v0/edgehostnames/ehn_1332?contractId=ctr_1-1TJZH5&groupId=grp_15225
X-Limit-Edgehostnames-Per-Contract-Limit: 100
X-Limit-Edgehostnames-Per-Contract-Remaining: 97
Response:
{
"edgeHostnameLink": "/papi/v0/edgehostnames/ehn_1332?contractId=ctr_1-1TJZH5&grp_15225"
}
List Contracts from
/papi/v0/contracts
and store the relevantcontractId
.List Groups, choose the relevant group, and store its
groupId
.List Products from
/papi/v0/products{?contractId}
and store the relevantproductId
with which to enable the edge hostname.Build an EdgeHostname POST object.
For a standard edge hostname, set
secure
tofalse
. This boolean flag does not refer to HTTPS, but to whatever additional level of security options the product enables. To create a secure edge hostname, you need to use the Secure Provisioning Service API instead.Setting the request’s
ipVersionBehavior
toIPV6_COMPLIANCE
allows both IPv4 and IPv6, but you need to be careful your origin servers support the latter.Set the
domainPrefix
to the origin hostname, for examplecustom.example.com
.Set the
domainSuffix
toedgesuite.net
.
POST the object to
/papi/v0/edgehostnames/{?contractId,groupId}
.Optionally GET the new edge hostname from the response’s
edgeHostnameLink
orLocation
header to poll its deployment status.
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
.
GET /papi/
Example: /papi/
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
contractId |
String | ctr_1-1TJZH5 |
Unique identifier for the contract. Remove the ctr_ prefix if using the value in other Akamai APIs. |
edgeHostnameId |
String | ehn_887436 |
Unique identifier for the edge hostname. Remove the ehn_ prefix if using the value in other Akamai APIs. |
groupId |
String | grp_15255 |
Unique identifier for the group. Remove the grp_ prefix if using the value in other Akamai APIs. |
Optional | |||
options |
String | mapDetails |
Comma-separated list of options to enable; mapDetails enables extra mapping-related information. |
Status 200 application/json
Response:
{
"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 Contracts from
/papi/v0/contracts
and store the relevantcontractId
.List Groups from
/papi/v0/groups
and store the relevantgroupId
.List Edge Hostnames from
/papi/v0/edgehostnames/{?contractId,groupId}
and store the relevantedgeHostnameId
.GET the edge hostname from
/papi/v0/edgehostnames/{edgeHostnameId}{?contractId,groupId}
.The EdgeHostname object is available within the response’s single-item
edgeHostnames.items
array.
List properties
This operation lists properties available for the current contract and group.
GET /papi/
Example: /papi/
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
contractId |
String | ctr_1-1TJZH5 |
Unique identifier for the contract. Remove the ctr_ prefix if using the value in other Akamai APIs. |
groupId |
String | grp_15225 |
Unique identifier for the group. Remove the grp_ prefix if using the value in other Akamai APIs. |
Status 200 application/json
Headers:
X-Limit-Properties-Per-Contract-Limit: 100
X-Limit-Properties-Per-Contract-Remaining: 99
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"
},
{
"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"
}
]
}
}
List Contracts from
/papi/v0/contracts
and store the relevantcontractId
.List Groups from
/papi/v0/groups
and store the relevantgroupId
.GET the list of properties from
/papi/v0/properties/{?contractId,groupId}
.Property objects are available from the response’s
properties.items
array.
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.
POST /papi/
Example: /papi/
Content-Type: application/json
Request:
{
"productId": "prd_Alta",
"propertyName": "my.new.property.com",
"cloneFrom": {
"propertyId": "prp_175780",
"version": 2,
"cloneFromVersionEtag": "a9dfe78cf93090516bde891d009eaf57",
"copyHostnames": true
}
}
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
contractId |
String | ctr_1-1TJZH5 |
Unique identifier for the contract. Remove the ctr_ prefix if using the value in other Akamai APIs. |
groupId |
String | grp_15225 |
Unique identifier for the group. Remove the grp_ prefix if using the value in other Akamai APIs. |
Status 201 application/json
Headers:
Location: /papi/v0/properties/prp_173137?contractId=ctr_1-1TJZH5&groupId=grp_15225
X-Limit-Properties-Per-Contract-Limit: 100
X-Limit-Properties-Per-Contract-Remaining: 98
Response:
{
"propertyLink": "/papi/v0/properties/prp_173137?contractId=ctr_1-1TJZH5&groupId=grp_15225"
}
Gather prerequisites:
List Contracts from
/papi/v0/contracts
and store the relevantcontractId
.List Groups from
/papi/v0/groups
and store the relevantgroupId
.List Products from
/papi/v0/products{?contractId}
and store the relevantproductId
with which to enable the property.
To create a property from scratch:
Optionally List Rule Formats from
/papi/v0/rule-formats
and store the desired feature catalog version.Build a Property POST object, optionally specifying the rule format, as in the example below.
To clone a property:
List Properties from
/papi/v0/properties/{?contractId,groupId}
and store the relevantpropertyId
from the property you want to clone.List the property’s versions from
/papi/v0/properties/{propertyId}/versions/{?contractId,groupId}
and select the version you want to clone.Store the version’s
propertyVersion
andetag
.Build a Property POST object.
Add a
Property.cloneFrom
sub-object.
POST the request:
POST the object to
/papi/v0/properties/{?contractId,groupId}
.Optionally GET the new property from the response’s
propertyLink
orLocation
header.
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:
GET /papi/
Example: /papi/
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
contractId |
String | ctr_1-1TJZH5 |
Unique identifier for the contract. Remove the ctr_ prefix if using the value in other Akamai APIs. |
groupId |
String | grp_15225 |
Unique identifier for the group. Remove the grp_ prefix if using the value in other Akamai APIs. |
propertyId |
String | prp_175780 |
Unique identifier for the property. Remove the prp_ prefix if using the value in other Akamai APIs. |
Status 200 application/json
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"
}
]
}
}
List Contracts from
/papi/v0/contracts
and store the relevantcontractId
.List Groups from
/papi/v0/groups
and store the relevantgroupId
.List Properties from
/papi/v0/properties/{?contractId,groupId}
and store the relevantpropertyId
.GET the property from
/papi/v0/properties/{propertyId}{?contractId,groupId}
The Property object is available in the response’s single-item
properties.items
array.
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.
DELETE /papi/
Example: /papi/
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
contractId |
String | ctr_1-1TJZH5 |
Unique identifier for the contract. Remove the ctr_ prefix if using the value in other Akamai APIs. |
groupId |
String | grp_15225 |
Unique identifier for the group. Remove the grp_ prefix if using the value in other Akamai APIs. |
propertyId |
String | prp_175780 |
Unique identifier for the property. Remove the prp_ prefix if using the value in other Akamai APIs. |
Status 200 application/json
Response:
{
"message" : "Deletion Successful."
}
List Contracts from
/papi/v0/contracts
and store the relevantcontractId
.List Groups from
/papi/v0/groups
and store the relevantgroupId
.List Properties from
/papi/v0/properties/{?contractId,groupId}
and store the relevantpropertyId
.Make a DELETE request to
/papi/v0/properties/{propertyId}{?contractId,groupId}
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.
GET /papi/
Example: /papi/
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
contractId |
String | ctr_1-1TJZH5 |
Unique identifier for the contract. Remove the ctr_ prefix if using the value in other Akamai APIs. |
groupId |
String | grp_15225 |
Unique identifier for the group. Remove the grp_ prefix if using the value in other Akamai APIs. |
propertyId |
String | prp_173136 |
Unique identifier for the property. Remove the prp_ prefix if using the value in other Akamai APIs. |
Status 200 application/json
Response:
{
"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"
}
]
}
}
List Contracts from
/papi/v0/contracts
and store the relevantcontractId
.List Groups from
/papi/v0/groups
and store the relevantgroupId
.List Properties from
/papi/v0/properties/{?contractId,groupId}
and store the relevantpropertyId
.GET a list of versions from
/papi/v0/properties/{propertyId}/versions/{?contractId,groupId}
.Version objects are available from the response’s
versions.items
array.
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.
POST /papi/
Example: /papi/
Content-Type: application/json
Request:
{
"createFromVersion": 1,
"createFromVersionEtag": "2641910c585cf67b"
}
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
contractId |
String | ctr_1-1TJZH5 |
Unique identifier for the contract. Remove the ctr_ prefix if using the value in other Akamai APIs. |
groupId |
String | grp_15225 |
Unique identifier for the group. Remove the grp_ prefix if using the value in other Akamai APIs. |
propertyId |
String | prp_173136 |
Unique identifier for the property. Remove the prp_ prefix if using the value in other Akamai APIs. |
Status 201 application/json
Headers:
Location: /papi/v0/properties/prp_173136/versions/2?contractId=ctr_1-1TJZH5&groupId=grp_15225
Response:
{
"versionLink": "/papi/v0/properties/prp_173136/versions/2?contractId=ctr_1-1TJZH5&groupId=grp_15225"
}
List Contracts from
/papi/v0/contracts
and store the relevantcontractId
.List Groups from
/papi/v0/groups
and store the relevantgroupId
.List Properties from
/papi/v0/properties/{?contractId,groupId}
and store the relevantpropertyId
.List the property’s versions from
/papi/v0/properties/{propertyId}/versions/{?contractId,groupId}
and store the relevant version’spropertyVersion
.Build a Property POST object.
POST the object to
/papi/v0/properties/{propertyId}/versions/{?contractId,groupId}
.Optionally GET the new version from the response’s
versionLink
orLocation
header.
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.
GET /papi/
Example: /papi/
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
contractId |
String | ctr_1-1TJZH5 |
Unique identifier for the contract. Remove the ctr_ prefix if using the value in other Akamai APIs. |
groupId |
String | grp_15225 |
Unique identifier for the group. Remove the grp_ prefix if using the value in other Akamai APIs. |
propertyId |
String | prp_173136 |
Unique identifier for the property. Remove the prp_ prefix if using the value in other Akamai APIs. |
propertyVersion |
Integer | 3 |
Property’s incremental version number. |
Status 200 application/json
Headers:
Etag: "71573b922a87abc3"
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"
}
]
}
}
Status 200 text/xml
Response:
<?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>
List Contracts from
/papi/v0/contracts
and store the relevantcontractId
.List Groups from
/papi/v0/groups
and store the relevantgroupId
.List Products from
/papi/v0/products{?contractId}
and store the relevantproductId
with which to enable the property.List Properties from
/papi/v0/properties/{?contractId,groupId}
and store the relevantpropertyId
.List the property’s versions from
/papi/v0/properties/{propertyId}/versions/{?contractId,groupId}
and store the relevantpropertyVersion
.Optionally to get XML metadata, specify an
Accept: text/xml
header.GET the version from
/papi/v0/properties/{propertyId}/versions/{propertyVersion}{?contractId,groupId}
.The Version object is available from the response’s single-item
versions.items
array.
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.
GET /papi/
Example: /papi/
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
contractId |
String | ctr_1-1TJZH5 |
Unique identifier for the contract. Remove the ctr_ prefix if using the value in other Akamai APIs. |
groupId |
String | grp_15225 |
Unique identifier for the group. Remove the grp_ prefix if using the value in other Akamai APIs. |
propertyId |
String | prp_173136 |
Unique identifier for the property. Remove the prp_ prefix if using the value in other Akamai APIs. |
Optional | |||
activatedOn |
String | STAGING |
If present, returns the latest version activated on the given network. |
Status 302 application/json
Headers:
Location: /papi/v0/properties/prp_173136/versions/2?contractId=ctr_1-1TJZH5&groupId=grp_15225
Response:
{
"versionLink": "/papi/v0/properties/prp_173136/versions/2?contractId=ctr_1-1TJZH5&groupId=grp_15225"
}
List Contracts from
/papi/v0/contracts
and store the relevantcontractId
.List Groups from
/papi/v0/groups
and store the relevantgroupId
.List Products from
/papi/v0/products{?contractId}
and store the relevantproductId
with which to enable the property.List Properties from
/papi/v0/properties/{?contractId,groupId}
and store the relevantpropertyId
.Optionally set the
activatedOn
query parameter toPRODUCTION
orSTAGING
to get the latest activated version.GET the latest version from
/papi/v0/properties/{propertyId}/versions/latest{?contractId,groupId,activatedOn}
.Make another GET request on the response object’s
versionLink
orLocation
header.
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.
GET /papi/
Example: /papi/
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
contractId |
String | ctr_1-1TJZH5 |
Unique identifier for the contract. Remove the ctr_ prefix if using the value in other Akamai APIs. |
groupId |
String | grp_15225 |
Unique identifier for the group. Remove the grp_ prefix if using the value in other Akamai APIs. |
propertyId |
String | prp_173136 |
Unique identifier for the property. Remove the prp_ prefix if using the value in other Akamai APIs. |
propertyVersion |
Integer | 3 |
Property’s incremental version number. |
Status 200 application/json
Response:
{
"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 Contracts from
/papi/v0/contracts
and store the relevantcontractId
.List Groups from
/papi/v0/groups
and store the relevantgroupId
.List Properties from
/papi/v0/properties/{?contractId,groupId}
and store the relevantpropertyId
.List the property’s versions from
/papi/v0/properties/{propertyId}/versions/{?contractId,groupId}
and store the relevant version’spropertyVersion
.GET the list of behaviors from
/papi/v0/properties/{propertyId}/versions/{propertyVersion}/available-behaviors{?contractId,groupId}
.Data is listed in the response’s
availableBehaviors.items
array, either thename
of the behavior or the rule formatschemaLink
that describes its basic requirements.
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.
GET /papi/
Example: /papi/
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
contractId |
String | ctr_1-1TJZH5 |
Unique identifier for the contract. Remove the ctr_ prefix if using the value in other Akamai APIs. |
groupId |
String | grp_15225 |
Unique identifier for the group. Remove the grp_ prefix if using the value in other Akamai APIs. |
propertyId |
String | prp_173136 |
Unique identifier for the property. Remove the prp_ prefix if using the value in other Akamai APIs. |
propertyVersion |
Integer | 3 |
Property’s incremental version number. |
Status 200 application/json
Response:
{
"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 Contracts from
/papi/v0/contracts
and store the relevantcontractId
.List Groups from
/papi/v0/groups
and store the relevantgroupId
.List Properties from
/papi/v0/properties/{?contractId,groupId}
and store the relevantpropertyId
.List the property’s versions from
/papi/v0/properties/{propertyId}/versions/{?contractId,groupId}
and store the relevant version’spropertyVersion
.GET the list of criteria from
/papi/v0/properties/{propertyId}/versions/{propertyVersion}/available-criteria{?contractId,groupId}
.Data is listed in the response’s
availableCriteria.items
array, either thename
of the criteria or the rule formatschemaLink
that describes its basic requirements.
List property hostnames
This lists all the hostnames assigned to a property version, which may be a subset of all available edge hostnames.
GET /papi/
Example: /papi/
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
contractId |
String | ctr_1-1TJZH5 |
Unique identifier for the contract. Remove the ctr_ prefix if using the value in other Akamai APIs. |
groupId |
String | grp_15255 |
Unique identifier for the group. Remove the grp_ prefix if using the value in other Akamai APIs. |
propertyId |
String | prp_175780 |
Unique identifier for the property. Remove the prp_ prefix if using the value in other Akamai APIs. |
propertyVersion |
Integer | 1 |
Property’s incremental version number. |
Status 200 application/json
Headers:
ETag: "6aed418629b4e5c0"
X-Limit-Hosts-Per-Property-Limit: 100
X-Limit-Hosts-Per-Property-Remaining: 98
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"
}
]
}
}
List Contracts from
/papi/v0/contracts
and store the relevantcontractId
.List Groups from
/papi/v0/groups
and store the relevantgroupId
.List Properties from
/papi/v0/properties/{?contractId,groupId}
and store the relevantpropertyId
.List the property’s versions from
/papi/v0/properties/{propertyId}/versions/{?contractId,groupId}
and store the relevant version’spropertyVersion
.GET the list of hostnames from
/papi/v0/properties/{propertyId}/versions/{propertyVersion}/hostnames/{?contractId,groupId}
.Hostname objects are available in the response’s
hostnames.items
array.
Update property 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.
PUT /papi/
Example: /papi/
Content-Type: application/json
Headers:
If-Match: "6aed418629b4e5c0"
Request:
[
{
"cnameType": "EDGE_HOSTNAME",
"cnameFrom": "m.example.com",
"cnameTo": "example.com.edgesuite.net"
},
{
"cnameType": "EDGE_HOSTNAME",
"edgeHostnameId": "ehn_895824",
"cnameFrom": "example3.com"
}
]
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
contractId |
String | ctr_1-1TJZH5 |
Unique identifier for the contract. Remove the ctr_ prefix if using the value in other Akamai APIs. |
groupId |
String | grp_15255 |
Unique identifier for the group. Remove the grp_ prefix if using the value in other Akamai APIs. |
propertyId |
String | prp_175780 |
Unique identifier for the property. Remove the prp_ prefix if using the value in other Akamai APIs. |
propertyVersion |
Integer | 1 |
Property’s incremental version number. |
Optional | |||
validateHostnames |
Boolean | true |
When false (the default), skips validation tests that would identify potential hostname-related problems within the response object’s errors and warnings arrays. See Property Hostname Errors for details on relevant error feedback. See Validation and Activation Time for details on the delays this might avoid. |
Status 200 application/json
Headers:
ETag: "6aed418629b4e5c0"
X-Limit-Hosts-Per-Property-Limit: 100
X-Limit-Hosts-Per-Property-Remaining: 98
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"
}
]
}
}
List Contracts from
/papi/v0/contracts
and store the relevantcontractId
.List Groups from
/papi/v0/groups
and store the relevantgroupId
.Optionally List Edge Hostnames and collect any relevant
edgeHostnameId
values to assign.List Properties from
/papi/v0/properties/{?contractId,groupId}
and store the relevantpropertyId
.List the property’s versions from
/papi/v0/properties/{propertyId}/versions/{?contractId,groupId}
and store the relevant version’spropertyVersion
andetag
.List the property’s hostnames and store the response’s
hostnames.items
array.Modify the contents of the array, optionally adding objects that represent new edge hostnames.
Optionally set the
validateHostnames
query parameter tofalse
if you don’t want to perform potentially slower validation tests on the set of hostnames. See Validation and Activation Time for guidance.PUT the array to
/papi/v0/properties/{propertyId}/versions/{propertyVersion}/hostnames/{?contractId,groupId,validateHostnames}
, passing in theetag
as anIf-Match
header.
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.
GET /papi/
Example: /papi/
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
contractId |
String | ctr_1-1TJZH5 |
Unique identifier for the contract. Remove the ctr_ prefix if using the value in other Akamai APIs. |
groupId |
String | grp_15225 |
Unique identifier for the group. Remove the grp_ prefix if using the value in other Akamai APIs. |
propertyId |
String | prp_173136 |
Unique identifier for the property. Remove the prp_ prefix if using the value in other Akamai APIs. |
propertyVersion |
Integer | 3 |
Property’s incremental version number. |
Status 200 application/json
Headers:
Etag: "a9dfe78cf93090516bde891d009eaf57"
X-Limit-Clientip-Per-Property-Limit: 10
X-Limit-Clientip-Per-Property-Remaining: 10
X-Limit-Elements-Per-Property-Limit: 100
X-Limit-Elements-Per-Property-Remaining: 74
X-Limit-Max-Clientip-Per-Match-Limit: 300
X-Limit-Max-Clientip-Per-Match-Remaining: 300
X-Limit-Max-Nested-Rules-Limit: 5
X-Limit-Max-Nested-Rules-Remaining: 4
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": {
"http_port": "80",
"tcip_enabled": "off",
"compression": "on",
"cachekeyhostname": "originhostname",
"forwardhostheader": "requesthostheader",
"hostname": "origin.test.com",
"type": "customer"
}
},
{
"name": "cpCode",
"options": { "cpcodeId": 12345 }
}
],
"children": []
}
}
This procedure simply gets a rule tree. To increment its rule format, see Update Rules to a Newer Set of Features below.
List Contracts from
/papi/v0/contracts
and store the relevantcontractId
.List Groups from
/papi/v0/groups
and store the relevantgroupId
.List Properties from
/papi/v0/properties/{?contractId,groupId}
and store the relevantpropertyId
.List the property’s versions from
/papi/v0/properties/{propertyId}/versions/{?contractId,groupId}
and store the relevant version’spropertyVersion
.GET the rule tree from
/papi/v0/properties/{propertyId}/versions/{propertyVersion}/rules/{?contractId,groupId}
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.
List Rule Formats and store the more recent rule format version string to which you want to update the rule tree.
Build a custom MIME type string using this template,
application/vnd.akamai.papirules.vYYYY-MM-DD+json
, wherevYYYY-MM-DD
is the variable rule format version string.GET the rule tree as described above, adding an
Accept
header that specifies the custom MIME type.Confirm the response object’s top-level
ruleFormat
reflects the desired version.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 digest for a rule tree
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.
HEAD /papi/
Example: /papi/
Headers:
Accept: application/vnd.akamai.papirules.latest+json
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
contractId |
String | ctr_1-1TJZH5 |
Unique identifier for the contract. Remove the ctr_ prefix if using the value in other Akamai APIs. |
groupId |
String | grp_15225 |
Unique identifier for the group. Remove the grp_ prefix if using the value in other Akamai APIs. |
propertyId |
String | prp_173136 |
Unique identifier for the property. Remove the prp_ prefix if using the value in other Akamai APIs. |
propertyVersion |
Integer | 3 |
Property’s incremental version number. |
Status 204
Headers:
Etag: "a9dfe78cf93090516bde891d009eaf57"
List Contracts from
/papi/v0/contracts
and store the relevantcontractId
.List Groups from
/papi/v0/groups
and store the relevantgroupId
.List Properties from
/papi/v0/properties/{?contractId,groupId}
and store the relevantpropertyId
.List the property’s versions from
/papi/v0/properties/{propertyId}/versions/{?contractId,groupId}
and store the relevant version’spropertyVersion
.Send a HEAD request to
/papi/v0/properties/{propertyId}/versions/{propertyVersion}/rules/{?contractId,groupId}
Store the value of the response’s
Etag
header and remove the surrounding double quote characters.
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.
PUT /papi/
Example: /papi/
Content-Type: application/vnd.akamai.papirules.latest+json
Headers:
If-Match: "a9dfe78cf93090516bde891d009eaf57"
Request:
{
"rules": {
"name": "default",
"children": [
{
"name": "Handle /my-path",
"criteriaMustSatisfy": "all",
"criteria": [
{
"name": "path",
"value": [ "/my-path" ]
}
],
"behaviors": [
{
"name": "caching",
"behavior": "max-age",
"ttl": "1m"
}
]
}
]
}
}
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
contractId |
String | ctr_1-1TJZH5 |
Unique identifier for the contract. Remove the ctr_ prefix if using the value in other Akamai APIs. |
groupId |
String | grp_15225 |
Unique identifier for the group. Remove the grp_ prefix if using the value in other Akamai APIs. |
propertyId |
String | prp_173136 |
Unique identifier for the property. Remove the prp_ prefix if using the value in other Akamai APIs. |
propertyVersion |
Integer | 3 |
Property’s incremental version number. |
Optional | |||
validateRules |
Boolean | true |
Set to true by default. When false , skips validation tests that would identify potential problems within the response object’s errors and warnings arrays. See the Debug section for details on this error feedback. See Validation and Activation Time for details on the delays this might avoid. |
Status 200 application/vnd.akamai.papirules.latest+json
Headers:
Etag: "418c2c1986051606324fbb316131e0bf"
X-Limit-Clientip-Per-Property-Limit: 10
X-Limit-Clientip-Per-Property-Remaining: 10
X-Limit-Elements-Per-Property-Limit: 100
X-Limit-Elements-Per-Property-Remaining: 74
X-Limit-Max-Clientip-Per-Match-Limit: 300
X-Limit-Max-Clientip-Per-Match-Remaining: 300
X-Limit-Max-Nested-Rules-Limit: 5
X-Limit-Max-Nested-Rules-Remaining: 4
Response:
{
"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"
}
]
}
]
}
}
This procedure simply modifies a rule tree. To assign a fixed rule format version to a rule tree, see Freeze a Rule Tree’s Feature Set below.
List Contracts from
/papi/v0/contracts
and store the relevantcontractId
.List Groups from
/papi/v0/groups
and store the relevantgroupId
.List Properties from
/papi/v0/properties/{?contractId,groupId}
and store the relevantpropertyId
.List the property’s versions from
/papi/v0/properties/{propertyId}/versions/{?contractId,groupId}
and store the relevant version’spropertyVersion
.Optionally get the existing rule tree object.
Modify the rule tree.
Optionally set the
validateRules
query parameter tofalse
if you don’t want to perform potentially long-running validation tests on the rule tree. See Validation and Activation Time for guidance.PUT the object to
/papi/v0/properties/{propertyId}/versions/{propertyVersion}/rules/{?contractId,groupId,validateRules}
.
Freeze a feature set for a rule tree
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:
GET the rule tree and store the URL you use to retrieve it.
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 islatest
.List available rule formats and store the most recent dated rule format version string.
Build a custom MIME type string using this template,
application/vnd.akamai.papirules.vYYYY-MM-DD+json
, wherevYYYY-MM-DD
is the variable rule format version string.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.
POST /papi/
Content-Type: application/json
Request:
{
"edgeHostname": "my-hostname-1.example.com.edgesuite.net"
}
Status 200 application/json
Response:
{
"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.
GET /papi/
Example: /papi/
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
contractId |
String | ctr_1-1TJZH5 |
Unique identifier for the contract. Remove the ctr_ prefix if using the value in other Akamai APIs. |
groupId |
String | grp_15225 |
Unique identifier for the group. Remove the grp_ prefix if using the value in other Akamai APIs. |
propertyId |
String | prp_173136 |
Unique identifier for the property. Remove the prp_ prefix if using the value in other Akamai APIs. |
Status 200 application/json
Headers:
X-RateLimit-Activations-Limit: 10
X-RateLimit-Activations-Remaining: 9
X-RateLimit-Activations-Reset: 139603655200
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"
]
}
]
}
}
List Contracts from
/papi/v0/contracts
and store the relevantcontractId
.List Groups from
/papi/v0/groups
and store the relevantgroupId
.List Properties from
/papi/v0/properties/{?contractId,groupId}
and store the relevantpropertyId
.GET a list of the property’s activations from
/papi/v0/properties/{propertyId}/activations/{?contractId,groupId}
.Activation objects are available in the response’s
activations.items
array.
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
toDEACTIVATE
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.
POST /papi/
Example: /papi/
Content-Type: application/json
Request:
{
"propertyVersion": 1,
"network": "STAGING",
"note": "Sample activation",
"notifyEmails": [
"you@example.com",
"them@example.com"
],
"acknowledgeWarnings": [
"msg_baa4560881774a45b5fd25f5b1eab021d7c40b4f"
]
}
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
contractId |
String | ctr_1-1TJZH5 |
Unique identifier for the contract. Remove the ctr_ prefix if using the value in other Akamai APIs. |
groupId |
String | grp_15225 |
Unique identifier for the group. Remove the grp_ prefix if using the value in other Akamai APIs. |
propertyId |
String | prp_173136 |
Unique identifier for the property. Remove the prp_ prefix if using the value in other Akamai APIs. |
Status 201 application/json
Headers:
Location: /papi/v0/properties/prp_173136/activations/atv_67037?contractId=ctr_1-1TJZFB&groupId=grp_15225
X-RateLimit-Activations-Limit: 10
X-RateLimit-Activations-Remaining: 9
X-RateLimit-Activations-Reset: 139603655200
Response:
{
"activationLink": "/papi/v0/properties/prp_173136/activations/atv_67037?contractId=ctr_1-1TJZFB&groupId=grp_15225"
}
List Contracts from
/papi/v0/contracts
and store the relevantcontractId
.List Groups from
/papi/v0/groups
and store the relevantgroupId
.List Properties from
/papi/v0/properties/{?contractId,groupId}
and store the relevantpropertyId
.Either get the property’s
latestVersion
or list all versions and store the relevant version’spropertyVersion
.Build an Activation POST object.
POST the object to
/papi/v0/properties/{propertyId}/activations/{?contractId,groupId}
.Optionally poll the new activation to check its deployment
status
.
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.
GET /papi/
Example: /papi/
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
activationId |
String | atv_1696855 |
Unique identifier for the activation. |
contractId |
String | ctr_1-1TJZH5 |
Unique identifier for the contract. Remove the ctr_ prefix if using the value in other Akamai APIs. |
groupId |
String | grp_15225 |
Unique identifier for the group. Remove the grp_ prefix if using the value in other Akamai APIs. |
propertyId |
String | prp_173136 |
Unique identifier for the property. Remove the prp_ prefix if using the value in other Akamai APIs. |
Status 200 application/json
Headers:
Retry-After: 600
Response:
{
"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"
}
]
}
}
List Contracts from
/papi/v0/contracts
and store the relevantcontractId
.List Groups from
/papi/v0/groups
and store the relevantgroupId
.List Properties from
/papi/v0/properties/{?contractId,groupId}
and store the relevantpropertyId
.List Activations for the property and store the relevant
activationId
.GET the activation from
/papi/v0/properties/{propertyId}/activations/{activationId}{?contractId,groupId}
.The Activation object is available in the response’s single-item
activations.items
array.
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.
DELETE /papi/
Example: /papi/
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
activationId |
String | atv_1696855 |
Unique identifier for the activation. |
contractId |
String | ctr_1-1TJZH5 |
Unique identifier for the contract. Remove the ctr_ prefix if using the value in other Akamai APIs. |
groupId |
String | grp_15225 |
Unique identifier for the group. Remove the grp_ prefix if using the value in other Akamai APIs. |
propertyId |
String | prp_173136 |
Unique identifier for the property. Remove the prp_ prefix if using the value in other Akamai APIs. |
Status 200 application/json
Response:
{
"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.
GET /papi/
Status 200 application/json
Response:
{
"ruleFormats": {
"items": [
"latest",
"v2015-08-08"
]
}
}
Get a request schema
Fetch the JSON schema for a particular request. These are typically linked from error messages about schema mismatches.
GET /papi/
Example: /papi/
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
filename |
String | EdgeHostnamesPostRequestV0.json |
Schema’s filename. |
Status 200 application/json
Response:
{
"type": "object"
}
Get a rule format 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.
GET /papi/
Example: /papi/
Parameter | Type | Sample | Description |
---|---|---|---|
Required | |||
productId |
String | prd_Site_Accel |
Unique identifier for the product. Remove the prd_ prefix if using the value in other Akamai APIs. |
ruleFormat |
String | latest |
Name of the rule format, either one frozen to a specific date, or representing the latest set of behaviors and criteria. |
Status 200 application/json
Response:
{
"type": "object",
"properties": {
"rules": { "type": "object" }
},
"required": [ "rules" ]
}
List Products from
/papi/v0/products{?contractId}
and store the relevantproductId
.List Rule Formats and store the relevant
ruleFormat
string.GET the rule format schema from
/papi/v0/schemas/products/{productId}/{ruleFormat}
.
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.
GET /papi/
Status 200 application/json
Response:
{
"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.
PUT /papi/
Content-Type: application/json
Request:
{
"ruleFormat": "v2015-08-08"
}
Status 200 application/json
Response:
{
"ruleFormat": "v2015-08-08"
}
This sets a new default rule format:
List Rule Formats and select the appropriate version.
Build a ClientSettings object, or modify a GET response with the new
ruleFormat
value.PUT the object to
/papi/v0/client-settings
.
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.
GET /papi/
Status 200 application/json
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"
}
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. |
etag |
String | A digest with which to check the data’s integrity. |
groupId |
String | A unique identifier for the prevailing group. |
propertyId |
String | A unique identifier for the property. |
propertyName |
String | A descriptive name for the property. |
propertyVersion |
Number | Identifies a property instance. |
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 | Required | Description |
---|---|---|---|
contractIds |
Array | ✓ | A set of string identifiers for contracts whose products can be applied to properties within a group. |
groupId |
String | ✓ | A unique identifier for the group. |
groupName |
String | ✓ | A descriptive label for the group. |
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 | Required | Description |
---|---|---|---|
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 |
---|---|---|
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 | Required | Description |
---|---|---|---|
cpcodeId |
String | ○ | A unique identifier for the CP code. |
cpcodeName |
String | ✓ | A descriptive label for the CP code. |
createdDate |
String | ○ | A time stamp for the CP code. |
productId |
String | ✓ | On POST, the product to assign to this 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 | Required | Description |
---|---|---|---|
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 . |
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 . |
productId |
String | ✓ | The product associated with the edge hostname. |
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 | Required | Description |
---|---|---|---|
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. |
contractId |
String | ○ | Identifies the contract under which the property was created. |
groupId |
String | ○ | Identifies the group to which the property is assigned. |
latestVersion |
Number | ○ | Specifies the most recent version of the property. |
note |
String | ○ | Further descriptive commentary. |
productId |
String | ○ | The product assigned to the property, required when POSTing a new property. |
productionVersion |
Number | ○ | The most recent version to be activated to the production network, otherwise null . |
propertyId |
String | ✓ | The property’s unique identifier. |
propertyName |
String | ✓ | A descriptive name for the property. |
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: |
|||
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. |
propertyId |
String | ✓ | Specifies the property to clone. |
version |
Number | ✓ | Specifies the version of the property to clone. |
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 | Required | Description |
---|---|---|---|
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. |
etag |
String | ○ | A digest with which to check the data’s integrity. |
Only appears 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 | Required | Description |
---|---|---|---|
createFromVersion |
Number | ✓ | The property version on which to base the new version. |
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 | Required | Description |
---|---|---|---|
cnameFrom |
String | ✓ | The original origin’s hostname. |
cnameTo |
String | ○ | The hostname for edge content, corresponding to the edge hostname object’s edgeHostnameDomain member. |
cnameType |
Enumeration | ✓ | Only one supported EDGE_HOSTNAME value. |
edgeHostnameId |
String | ✓ | A unique identifier for the edge hostname. |
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:
Member | Type | Required | Description |
---|---|---|---|
behaviors |
Array | ✓ | A series of behavior objects. Optional on nested rules. |
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. |
name |
String | ✓ | A description of the rule. The top-level rule must be named default . |
options |
Rule.option | ○ | Flags that apply to the top-level rule object. |
Rule.options | |||
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 | Required | Description |
---|---|---|---|
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. |
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 | Required | Description |
---|---|---|---|
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 | Required | Description |
---|---|---|---|
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 | |||
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. |
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 amatchOperator
ofIS_ONE_OF
. The second rule could specify the samecontentType
criteria, only with amatchOperator
ofIS_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, theclientIp
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 istrue
, 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 thisuuid
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 ofcriteriaLocked
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.
Name | Description |
---|---|
AKA_PM_CACHEABLE_OBJECT |
Either true if the requested object is cacheable, or false if not. |
AK_BASE_URL |
The incoming request’s URL path, without filename and extension. |
AK_CLIENT_IP |
Client IP address as seen by the Akamai server, possibly overridden by X-Forwarded-For or Akamai-Client-IP request headers. |
AK_CLIENT_REAL_IP |
The client IP address as seen by the Akamai server, ignoring any request headers. |
AK_CLIENT_RTT |
Milliseconds elapsed for the TCP round-trip (RTT) between client and edge server. |
AK_CLIENT_TRANSFER_TIME |
Milliseconds elapsed to transfer content from edge to client. This value is only available after the client response completes. Applies only to custom log fields. |
AK_CLIENT_TURNAROUND_TIME |
Milliseconds elapsed for the combined initial request (AK_CLIENT_RTT ) plus the response’s transfer time (AK_CLIENT_TRANSFER_TIME ). This value is only available after the client response completes. Applies only to custom log fields. |
AK_CONNECTED_CLIENT_IP |
The IP on the TCP socket, either client or a redirecting ghost. |
AK_CPCODE |
The CP code associated with the request. |
AK_CURRENT_TIME |
The epoch time when edge metadata is applied to the request. If necessary, use the setVariable behavior to convert epoch time values to other time formats. |
AK_DOMAIN |
The hostname without the initial subdomain, such as example.com when requesting www.example.com . |
AK_EXTENSION |
The filename extension of the incoming request. |
AK_FILENAME |
The complete filename of the incoming request. |
AK_FIREWALL_ALERTED_RULES |
With webApplicationFirewall enabled, a colon-separated list of IDs for firewall rules that triggered an alert for the current request. |
AK_FIREWALL_DENY_RULEID |
With webApplicationFirewall enabled, the ID for a firewall rule set to deny the request when the rule triggers. |
AK_FIREWALL_DETECTED_RULES |
With webApplicationFirewall enabled, a colon-separated list of IDs for all firewall rules that apply to the request. |
AK_GHOST_IP |
The IP address on which end client requests are received, and ultimately resolve for the end user. |
AK_GHOST_SERVICE_IP |
The edge server IP address used to forward a request, also commonly known as the machine IP. This is the IP address the origin server sees as the client IP when it receives a request from the edge. |
AK_HOST_CNAME_CHAIN |
A space-delimited list of the CNAME chain provided by DNS lookup on the incoming Host header. |
AK_HOST |
The incoming request’s hostname. |
AK_METHOD |
The request method, such as GET , PUT , POST , or HEAD . |
AK_ORIGINAL_URL |
The original URL before any processing by Akamai Edge servers. |
AK_PATH |
The original URL path as seen by the Akamai Edge server. |
AK_PROTOCOL_NEGOTIATION |
The protocol negotiated with the client when NPN or ALPN is in use. Under HTTP, possible values are http/1.1 or http/1.0 . For HTTP2, values are h2-14 or h2 . For SPDY, values are spdy/3.1 , spdy/3 or spdy/2 . |
AK_QUERY |
The URL’s entire query string. |
AK_REQUEST_ID |
Unique identifier for each request on the edge server, the same as reported in logs. |
AK_SCHEME |
The request scheme, either http or https . |
AK_SLOT |
The incoming request’s slot number. |
AK_TLS_CIPHER_NAME |
For HTTPS and SPDY requests, specifies the name of the cipher used for the SSL connection, otherwise NO-CIPHER for HTTP requests. |
AK_TLS_ENCRYPTION_BITS |
Bits of encryption used for the request. |
AK_TLS_PREFERRED_CIPHERS |
The value of the request’s security:essl.slot-assignment.preferred-ciphers tag. |
AK_TLS_SNI_NAME |
The SNI name submitted by the client. |
AK_TLS_VERSION |
The TLS version used for the connection. |
AK_URL |
The incoming request’s entire URL. |
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:
Member | Type | Description |
---|---|---|
Required | ||
name |
String | The underlying root name of the variable, which must be unique within the set of variables . |
hidden |
Boolean | When enabled, the variable is suppressed from session response headers, often used to test content as described in the Debugging section. |
sensitive |
Boolean | When enabled, the variable is suppressed from session responses as hidden ones, but it also can’t be invoked within any behaviors that assign values to cookies or response headers. You also can’t assign a sensitive variable to another one that is not sensitive , and you can’t add it to custom logging fields. Use this more stringent option for any personally identifiable information, typically after initially testing on the staging network. |
Optional | ||
description |
String | Text for you to keep track of how the variable is used. |
value |
String | Initializes a default value. Omitting this member equates to initializing an empty string. |
There are three different ways variable names appear:
Within the
variables
declaration, you specify the baseVAR_NAME
.When you modify the variable with
setVariable
or match it withmatchVariable
as described below, you add aPMUSER_
prefix to refer to the variable name asPMUSER_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 thevariableError
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
totrue
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:
As discussed in the section on Declaring Variables, each variable defined in the default rule features two
hidden
andsensitive
options, and you first need to disable both for any variables you want to inspect.Activate the property that includes the variables on the staging network.
Once content activates, send a
Pragma:akamai-x-get-extracted-values
header in your test requests. The response includesX-Akamai-Session-Info
headers that reflect the value of each declared variable.After debugging, re-enable the
hidden
andsensitive
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:
Code | Description |
---|---|
200 | The request is successful. |
201 | The new item was successfully created. |
204 | The item was successfully removed. |
302 | The requested item is available at the link provided. |
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
Code | Type | Problem |
---|---|---|
400 | http/bad-request |
The system cannot understand your request, perhaps due to malformed data. |
401 | http/unauthorized |
The request requires authentication. |
403 | http/forbidden |
The authorization token does not allow access to the resource. For example, the request may specify products not authorized on a contract. |
404 | http/not-found |
Unable to locate the requested resource. |
405 | http/method-not-allowed |
The specified HTTP method is not supported for this resource. |
406 | http/not-acceptable |
The content-type restriction specified by your Accept header is not supported. |
412 | etag-conflict |
The Etag you provided does not match the most recent edit. The data has changed since initially accessed. Learn more. |
412 | http/precondition-failed |
Preconditions such as If-Match or If-Not-Match are not satisfied. The data has changed since initially accessed. Learn more. |
415 | http/unsupported-media-type |
The requested MIME format is not allowed. |
500 | http/internal-server-error |
The platform experienced an unknown error. |
501 | http/not-implemented |
The platform does not support the requested functionality. |
Data errors
Code | Type | Problem |
---|---|---|
400 | json-mapping-error |
Your input could not be validated against the schema, most likely because it is not the expected data type. |
400 | json-parse-error |
Your input could not be parsed as JSON. The problem response provides details on the location of the parsing error. |
400 | json-schema-invalid |
Your input does not validate against the data’s schema. |
400 | missing-request-body-field |
Your request is missing a Body field. |
400 | missing-required-parameter |
The request URL is missing a required parameter, which is detailed in the problem response. |
Edge hostname errors
Code | Type | Problem |
---|---|---|
400 | edgehostname/bad-suffix |
The edge hostname’s specified domainSuffix is not allowed. Learn more. |
400 | edgehostname/not-available |
The specified edge hostname is not available. |
403 | edgehostname/create-forbidden |
The product you assigned to the edge hostname is not included in your contract. Learn more. |
429 | limit-exceeded.edgehostnames_per_contract |
You exceeded the limit on the number of edge hostnames for your contract, and must deactivate one before proceeding. Contact your Akamai representative for information on how to increase this limit. Learn more. |
500 | edgehostname/create-error |
The platform encountered an unknown error when trying to create the edge hostname. |
Property hostname errors
Code | Type | Problem |
---|---|---|
400 | property-version-hostname/bad-cnameto |
The cnameTo value references an edge hostname that doesn’t exist. |
400 | property-version-hostname/edgehostname-mismatch |
You supplied both a cnameTo and edgeHostnameId that reference different hostnames. Learn more. |
400 | property-version-hostname/missing-cnameto-or-edgehostnameid |
You need to specify either a cnameTo or a edgeHostnameId member. Learn more. |
501 | property-version-hostname/unsupported-cnametype |
You can only specify a property hostname whose cnameType is EDGE_HOSTNAME . Learn more. |
An additional set of errors may be listed within Hostname objects that prevent you from activating the property version:
Type | Description |
---|---|
generic_ |
An origin may not specify the same hostname as a property. |
hostnames. |
The hostname is not formatted properly. |
hostnames. |
The AkamaiHD hostname is invalid. The prefix for a.akamaihd.net has a maximum 16 alphanumeric and underscore characters. |
hostnames. |
The hostname may not specify akamaized.net . |
hostnames. |
Make sure your origin can handle IPv6 traffic. |
hostnames. |
The hostname is listed more than once. |
hostnames. |
Specify at least one property hostname. |
hostnames. |
The hostname may not be empty. |
hostnames. |
Avoid underscore characters in hostnames, which may cause problems for some DNS resolvers. |
hostnames. |
A secure edge hostname is incompatible with your non-secure property. |
hostnames. |
You have reached the maximum number of hostnames per property. Either reconfigure using the instantConfig behavior, split your hostnames across more than one property, or consult with your account representative. |
hostnames. |
You have exceeded the optimal number of hostnames per property. Either reconfigure using the instantConfig behavior, split your hostnames across more than one property, or consult with your account representative. |
hostnames. |
The hostname is formatted incorrectly, and can’t begin with a hyphen. |
hostnames. |
A property hostname needs to reference a corresponding edge hostname. |
hostnames. |
An edge hostname is incompatible with your secure property. |
hostnames. |
An edge hostname is incompatible with your secure property. |
hostnames. |
The hostname is formatted incorrectly, and can’t begin with a hyphen. |
hostnames. |
The edge hostname is unavailable, and may not exist. |
Property errors
Code | Type | Problem |
---|---|---|
400 | property/invalid-name |
Property names may only use alphanumeric characters, underscores, dashes, and dots. |
400 | property/name-in-use |
Each property name must be unique. |
403 | property-version/lock-error |
Only Akamai representatives can change read-only behaviors, criteria, and child rules. Learn more. |
403 | property-version/lock-error/behaviors-changed |
Read-only behaviors have been added, removed, changed, or moved. Learn more. |
403 | property-version/lock-error/criteria-changed |
Read-only criteria have been added, removed, changed, or moved. Learn more. |
403 | property-version/lock-error/rule-structure-changed |
Read-only rules have been added, removed, changed, or moved. Learn more. |
404 | property-deletion/not-found |
The property you are trying to delete is unknown. |
404 | property-version/not-found |
The requested Property version is not available. |
429 | limit-exceeded.properties_per_contract |
You exceeded the limit on the number of properties for your contract, and must deactivate one before proceeding. Contact your Akamai representative for information on how to increase this limit. Learn more. |
500 | property-version/error |
The platform could not process your request on the specified property version. |
Activation errors
Code | Type | Problem |
---|---|---|
400 | activation/bad-notifyemails |
Activations require at least one email address specified in the notifyEmails array. Learn more. |
400 | activation/missing-compliance-record-info |
For Akamai representatives activating customers’ properties, nonComplianceReason cannot be NONE without having a valid unitTested , peerReviewedBy , and customerEmail . Either provide those values or change to a different nonComplianceReason . |
400 | activation/missing-compliance-record |
Akamai representatives must provide a compliance record before activating a property on customers’ behalf on the production network. For details, see the required schema: /papi/v0/schemas/request/CreateNewActivationRequestV0.json #/properties/complianceRecord . |
400 | activation/self-peer-review |
Akamai representatives may not peer review their own activations. |
400 | activation/warnings-not-acknowledged |
Before proceeding, you must acknowledge the activation warnings listed in the problem response. Learn more. |
403 | property-version/already-activated |
The specified property version has already been activated. To make changes you must first create a new property version. |
404 | activation-cancellation/not-found |
The activation you are trying to cancel is unknown. Learn more. |
422 | activation-cancellation/unprocessable-status |
The activation is not in a pending state, so it can’t be canceled. Learn more. |
422 | activation/already-activated |
The property version has already been activated. |
422 | activation/still-pending |
The property version is currently pending activation or deactivation. Please wait until the operation is complete before starting another activation or deactivation. |
429 | rate-limit-exceeded.activations |
You made too many activations in the amount of time allowed for your contract. The problem response provides details on when you can request more activations. Learn more. |
500 | activation-cancellation/cancel-error |
The platform could not cancel the activation. |
500 | activation/property_activation_failed |
The property activation failed. |
500 | deactivation/property_deactivation_failed |
The property deactivation failed. |
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:
Type | Description |
---|---|
compatible_ |
Rules include incompatible behaviors. |
condition_ |
You must upgrade to a new version of a criteria. |
deprecated |
The behavior has been deprecated. |
deprecated_ |
The behavior has been removed. |
deprecated_ |
The behavior has been deprecated. |
duplicate_ |
Two behaviors of the same type are inappropriately placed within the same rule. |
feature_ |
A new version of the behavior is available, requiring an upgrade. |
feature_ |
The property needs to be upgraded to replace a deprecated behavior. |
feature_ |
The property needs to be upgraded to replace a deprecated behavior, but this version can’t be edited. Create a new version if necessary. |
feature_ |
A new version of the behavior is available, requiring an upgrade. |
generic_ |
A new version of the behavior is available that may require a different set of options. |
generic_ |
A specified NetStorage account is not associated with this property’s group. |
generic_ |
Your auxiliary certificate list specifies trusted items not reflected in what your origin behavior specifies. Confirm they are accurate, and contact your account team if there is a problem. |
generic_ |
Your auxiliary certificate list specifies trusted items not reflected in what your origin behavior specifies. Confirm they are accurate, and contact your account team if there is a problem. |
generic_ |
Your auxiliary certificate list specifies trusted items not reflected in what your origin behavior specifies. Confirm they are accurate, and contact your account team if there is a problem. |
generic_ |
The origin behavior’s customValidCnValues option is missing CN/SAN match values from the auxiliary certificates list, so an ordinarily trusted certificate may not be trusted, and may result in a service outage. |
generic_ |
Confirm the origin behavior’s customValidCnValues option includes all CN/SAN values from the auxiliary certificates list. |
generic_ |
Values in the origin behavior’s customValidCnValues option may contain a star (* ) character, but it is interpreted literally. |
incompatible_ |
There is an incompatibility with a specific criteria within the same rule. |
incompatible_ |
There is an incompatibility with a specific behavior within the same rule. |
incompatible_ |
There is an incompatibility with a set of match criteria. |
incompatible_ |
There is an incompatibility with a criteria in a parent rule. |
incompatible_ |
There is an incompatibility with a criteria that appears in the same rule. |
required_ |
The default rule requires a behavior for the property to work. |
too_ |
There are more instances of the specified behavior than allowed within a property. |
unknown_ |
The criteria is not supported, and you need to remove it before activating your property. |
unknown_ |
The behavior is not supported, and you need to remove it before activating your property. |
unknown_ |
The behavior or criteria specifies an unknown option. |
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:
Type | Description |
---|---|
advanced_ |
A rule specifies advanced metadata that potentially overrides other configurations specified in previous rules. |
badly_ |
The behavior specifies invalid XML metadata. |
conflicting_ |
A behavior may not work as expected because advanced metadata may cause conflicts. |
Contract, account, and CP code errors
Code | Type | Problem |
---|---|---|
429 | cpcode/rate-limit-reached |
You made too many CP code requests. Try again later. |
403 | cpcode/invalid-services |
The current product does not allow you to create CP codes. |
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.
Type | Description |
---|---|
cloudlets_ |
For cloudletsOrigin criteria to work, there must be an allowCloudletsOrigins placed within a parent rule. |
incompatible_ |
The cloudletsOrigin criteria only works when the origin behavior’s originType is set to CUSTOMER , NET_STORAGE , or APPLICATION_LOAD_BALANCER . |
incompatible_ |
Specifying cloudletsOrigin along with any other criteria may make the origin inaccessible during a client request. |
need_ |
To use requestMethod to match PATCH requests, you need to enable the allowPatch behavior. |
need_ |
To use requestMethod to match POST requests, you need to enable the allowPost behavior. |
need_ |
The tokenAuthorization match requires a verifyTokenAuthorization behavior in a parent rule with its failureResponse option disabled. |
need_ |
To use requestMethod to match the specified method, you need to enable the webdav behavior. |
onlyonedge |
Criteria such as clientIp , clientIpVersion , userLocation , and userNetwork only match on edge servers, not when requests are forwarded to other Akamai servers. Contact your Akamai representative for guidance. |
options_ |
Requests that specify the OPTIONS method are always passed to the origin, so you can’t use requestMethod to match them. |
origin_ |
The cloudletsOrigin behavior must be paired with an origin behavior. |
requires_ |
The bucket criteria can only be used along with the spdy behavior. |
should_ |
When modifying content based on the deviceCharacteristic , you should use the modifyOutgoingResponseHeader behavior to specify a Vary: User-Agent header. |
suggest_ |
Rather than randomly segmenting your traffic, consider applying audienceSegmentation to divide users into different groups based on a persistent cookie. |
upper_ |
The match specifies a lowerBound value that is greater than the upperBound . |
warn_ |
Requests that don’t include an X-Forwarded-For header do not match. Consider disabling the useOnlyFirstXForwardedForIp option. |
Behavior-specific errors
These errors relate to how specific behaviors execute. They may be listed within Rule objects, and may prevent you from activating the property version.
Type | Description |
---|---|
206override |
The responseCode behavior’s 206override option allows the 206 response to be overwritten, not recommended because it applies to byte-range responses. Please confirm you want to do this, and contact your Akamai representative for guidance. |
advanced_ |
The imageManager behavior is configured to use a custom policy, but the behavior is disabled, so it has no effect. |
advanced_ |
When overriding the default policy, if the specified policyToken is not found, imageManager applies the default and does not save the one you specified. |
applicationloadbalancer_ |
For an APPLICATION_LOAD_BALANCER origin to work, an applicationLoadBalancer behavior must also be enabled. |
aws_ |
To set a third-party origin hostname, set the verificationMode to THIRD_PARTY or CUSTOM . |
basic_ |
You can’t specify both the redirect and redirectplus behaviors. |
beware_ |
A behavior that implements a persistent connection may mean that a specified condition no longer works. |
cache_ |
With cacheKeyIgnoreCase enabled, you should not specify a case-sensitive match, otherwise two different requests that vary only by case may get different results, even though they refer to the same cached object. |
cache_ |
With cacheKeyIgnoreCase enabled, you should not specify a case-sensitive match, otherwise two different requests that vary only by case may get different results, even though they refer to the same cached object. |
cache_ |
With cacheKeyIgnoreCase enabled, you should not specify a case-sensitive match, otherwise two different requests that vary only by case may get different results, even though they refer to the same cached object. |
cachekeyqueryparams |
Since NET_STORAGE origin servers do not honor query strings, set cacheKeyQueryParams to IGNORE_ALL to avoid more than cache key for the same object. |
caching |
You are potentially caching content identified as personallyIdentifiableInformation , so you should set the caching behavior to NO_STORE or BYPASS_CACHE . |
caching_ |
The specified behavior only applies to cachable content, not when caching is set to NO_STORE or BYPASS_CACHE . |
caching_ |
The sureRoute behavior only applies when caching is set to NO_STORE . |
caching_ |
For best performance when using a NET_STORAGE origin , set the caching ttl to over 10 minutes. |
can_ |
You can’t specify more than one origin behavior with a verificationMode of both PLATFORM_SETTINGS and CUSTOM . |
centralauth |
A NET_STORAGE origin can’t be used along with centralAuthorization . |
changing_ |
CP codes specified by imageManager affect cached images. If you change the CP codes after deploying the images in a production environment, image caches get refreshed, which may overload your origin. |
conflict_ |
Applying a behavior that modifies Cache-Control or Expires headers may interfere with caching when both are applied to the same request. |
cookie_ |
The edgeLoadBalancingOrigin behavior’s enableSessionPersistence is on, but edgeLoadBalancingDataCenter is missing a cookieName . |
cookie_ |
The edgeLoadBalancingOrigin behavior’s enableSessionPersistence is off, but edgeLoadBalancingDataCenter specifies a cookieName that does not work. |
cpcode_ |
The cpCode behavior can’t appear within the same rule as imageManager , which specifies its own CP code settings. |
customer_ |
If the origin server does not support etags, the largeFileOptimization behavior may not work correctly, and data may be corrupted. |
disable_ |
When enabling edgeSideIncludes , do not set gzipResponse to ALWAYS work, otherwise content goes through compression and decompression unnecessarily. |
dontallow_ |
The downgradeProtocol behavior is not allowed when caching is set to NO_STORE or BYPASS_CACHE . |
dontallow_ |
The downgradeProtocol behavior is not allowed along with allowDelete . |
dontallow_ |
The downgradeProtocol behavior is not allowed along with modifyOutgoingRequestHeader . |
dontallow_ |
The downgradeProtocol behavior is not allowed for content marked as personallyIdentifiableInformation . |
dontallow_ |
The downgradeProtocol behavior is not allowed along with allowPost . |
dontallow_ |
The downgradeProtocol behavior is not allowed along with allowPut . |
downstream_ |
The shutr behavior busts downstream caches to prevent non-Akamai proxies from tampering with content. If downstreamCache is set to values other than BUST , shutr overrides it. |
downstream_ |
A specified behavior may expose content identified as personallyIdentifiableInformation . You should set a downstreamCache to BUST the cache, or ALLOW it but with sendPrivate enabled. |
downstream_ |
A specified behavior may expose content identified as personallyIdentifiableInformation . You should set a downstreamCache to BUST the cache, or ALLOW it but with sendPrivate enabled. |
elb_ |
When using an EDGE_LOAD_BALANCING_ORIGIN_GROUP origin , you can’t specify {{Origin Hostname}} in the customValidCnValues . |
elb_ |
To specify an origin of EDGE_LOAD_BALANCING_ORIGIN_GROUP , you must also enable an edgeLoadBalancingOrigin behavior that defines the origin. |
elb_ |
An edgeLoadBalancingAdvanced behavior requires an accompanying edgeLoadBalancingOrigin . |
empty_ |
The edgeLoadBalancingDataCenter is invalid because its cookie value is empty and enableFailover is turned off. |
extension_ |
To apply this behavior to large files, you should match the fileExtension or otherwise avoid applying the behavior to small files, for which it may cause a delay. |
filename_ |
You should enable limitBitRate with a filename , fileExtension , or path match. |
g2o_ |
You can’t use modifyOutgoingResponseHeader to modify the X-Akamai-G2O-Auth-Data and X-Akamai-G2O-Auth-Sign headers specified by the g2oheader behavior. |
http2_ |
The http2 behavior requires that the property is_secure . |
includeallqs |
If one cacheId behavior is set to INCLUDE_ALL_QUERY_PARAMS , there can’t be another in the same rule that includes or excludes specific parameters. |
includeqs |
If one cacheId behavior is set to include a specific set of query parameters, there can’t be another in the same rule that excludes others. |
incompatible_ |
The failAction behavior is not compatible when the origin is set to EDGE_LOAD_BALANCING_ORIGIN_GROUP . |
incompatible_ |
You can’t apply the rewriteUrl and baseDirectory behaviors to the same request. |
incompatible_ |
The siteShield behavior is incompatible with predictivePrefetching . |
incompatible_ |
You can’t specify allowCloudletsOrigins with any matching criteria. |
incompatible_ |
You can’t specify allowCloudletsOrigins along with any other behaviors. It must be alone in its own rule. |
incompatible_ |
deliveryReceipt is not compatible when the origin is NET_STORAGE . |
incompatibleesi |
You may only enable akamaizer with edgeSideIncludes . |
incompatibleredirect |
The responseCode behavior may not work as expected along with redirect , because they use different status codes. |
invalid_ |
The origin hostname is AWS and the verificationMode is CUSTOM , but the originCertsToHonor is not set to STANDARD_CERTIFICATE_AUTHORITIES or COMBO . |
ip_ |
You should specify your origin server as a hostname. IP addresses may be abruptly reassigned and negatively affect your service. |
lfo_ |
A tieredDistribution whose tieredDistributionMap doesn’t specify CH or CH2 can’t be applied within a secure property along with a largeFileOptimization whose useVersioning is enabled. |
logging_ |
You are using report to log values for cookies in responses identified as personallyIdentifiableInformation . Make sure the cookies are not exposing sensitive information. |
min_ |
Any rule that contains imageManager must also specify a caching behavior with a ttl of at least 1 day. |
missing_ |
The watermarkUrl behavior requires a corresponding edgeImageConversion in the same rule or in a child rule. |
missing_ |
An edgeLoadBalancingDataCenter requires an accompanying edgeLoadBalancingOrigin . |
missing_ |
To use simulateErrorCode for the ERR_NO_GOOD_FWD_IP error, healthDetection must be enabled. |
mobile_ |
Mobile redirect only supports the 302 status code. |
mobile_ |
A mobile redirect can’t be used in the same rule as a default redirect . |
must_ |
To enable an origin of EDGE_LOAD_BALANCING_ORIGIN_GROUP , you must also define a cloudletsOrigin rule. |
need_ |
The prefetchable behavior needs to be enabled by a filename or fileExtension match. |
need_ |
The downgradeProtocol behavior is only allowed when the origin is set to CUSTOMER . |
need_ |
To enable the edgeLoadBalancingOrigin behavior’s enableSessionPersistence option, you need to configure an edgeLoadBalancingDataCenter . |
needs_ |
The akamaizer behavior needs to be enabled for akamaizerTag to work. |
needs_ |
There must be at least one akamaizerTag for akamaizer to work. |
needs_ |
The edgeSideIncludes behavior may only be used in rules with matching criteria such as path , contentType , or filename . |
needs_ |
You may only enable akamaizer within a contentType match. |
netstorage_ |
The origin needs to be set to NET_STORAGE if the hostname is a subdomain of download.akamai.com , upload.akamai.com , or postfile.akamai.com . |
no_ |
You may not use instantConfig when the cacheKeyHostname of the origin is set to REQUEST_HOST_HEADER . |
nonce_ |
The g2oheader behavior’s nonce should be different than its secretKey . |
not_ |
You can’t use verifyTokenAuthorization when segmentedContentProtection is enabled . |
not_ |
The constructResponse response body should be valid XHTML. |
notallow_ |
The downgradeProtocol behavior can’t be enabled by a fileExtension match. |
notallow_ |
The downgradeProtocol behavior can’t be enabled by a filename match. |
notallow_ |
The downgradeProtocol behavior can’t be enabled by a requestProtocol match. |
objects_ |
Objects served with edgeSideIncludes may not be larger than 1MB. |
origin_ |
An old origin version specifies a cachekeyhostname of requesthostheader . |
origin_ |
An old origin version specifies an elb_origin_group of type . |
origin_ |
edgeLoadBalancingOrigin doesn’t work unless the origin is set to EDGE_LOAD_BALANCING_ORIGIN_GROUP . |
origin_ |
You should not use the g2oheader behavior when the origin is set to NET_STORAGE . |
origin_ |
The origin can’t be set to NET_STORAGE if segmentedMediaOptimization is set to stream LIVE . |
performance_ |
The akamaizer behavior is not recommended for sites that routinely serve more than 100 hits per second. |
prefetch |
The instant behavior is a superset of prefetch , and they are mutually exclusive. Remove either behavior. |
prefetching_ |
The prefetchable behavior has no effect unless you apply prefetch to the page users access, and which contains links to the prefetchable objects. |
prefetching_ |
The siteShield behavior is incompatible with prefetching. |
prune_ |
A NET_STORAGE origin server ignores query parameters, so it’s more efficient to disable the rewriteUrl behavior’s keepQueryString option. |
receiptdelivery_ |
Applying deliveryReceipt requires that you enable allowPost . |
receiptdelivery_ |
Applying deliveryReceipt requires that you set caching to BYPASS_CACHE . |
receiptdelivery_ |
deliveryReceipt requires that the property is_secure . |
regex_ |
When siteShield is used in a non-secure property, the domain name of the ssmap must end with .akamai.net . |
regex_ |
When siteShield is used in a secure property, the domain name of the ssmap must end with .akamaiedge.net . |
regex_ |
The sureRoute behavior’s customMap must be a subdomain of akasrg.akamai.com . |
requireakamaizer |
The savePostDcaProcessing behavior doesn’t work properly unless akamaizer is enabled. |
required_ |
For a behavior to specify a CNAME chain, the instantConfig behavior must also be enabled, or the property must be secure. |
required_ |
When your origin is set to NET_STORAGE , set the cacheError with a ttl of at least 30 seconds. |
required_ |
The origin hostname is AWS, the verificationMode is set to CUSTOM , and originCertsToHonor is set to STANDARD_CERTIFICATE_AUTHORITIES or COMBO , but standardCertificateAuthorities doesn’t include THIRD_PARTY_AMAZON . |
requires_ |
To set the cache’s ID, the caching behavior must be enabled. |
requires_ |
The imageManager behavior requires a fileExtension match. ??? |
requires_ |
The http2 and spdy behaviors can only be enabled within a hostname match. |
requires_ |
The randomSeek behavior works best when mediaFileRetrievalOptimization is enabled. |
requires_ |
To apply instantConfig requires a non-secure property. |
requires_ |
You can’t use cacheKeyRewrite when the origin behavior’s cacheKeyHostname is set to REQUEST_HOST_HEADER . |
requires_ |
You can only enable the webdav behavior when matching a requestMethod . |
requirescaching |
When using cachePost , you should also use caching to define a caching strategy. |
requirespost |
The savePostDcaProcessing behavior requires either allowPost or cachePost to be enabled. |
requirespostcaching |
The savePostDcaProcessing behavior requires cachePost to be enabled. |
responsecode_ |
The response code defined in constructResponse and responseCode do not match. |
saas_ |
When using a SAAS_DYNAMIC_ORIGIN origin , you can’t specify {{Origin Hostname}} in the customValidCnValues . |
salt_ |
The verifyTokenAuthorization behavior’s salt option will be removed in a future release, so you should remove it from your code. |
scheduledinvalidation |
When the origin is NET_STORAGE , the scheduleInvalidation behavior’s repeatInterval must be at least 5 minutes. |
secret_ |
The g2oheader behavior’s secretKey must be at least 10 alphanumeric characters long. |
spdy_ |
The spdy behavior requires that the property is_secure . |
sr_ |
A sureRoute behavior specifies a type of CUSTOM_MAP , and the customMap does not match what is specified by siteShield . |
sr_ |
With siteShield enabled, the optimiziation type for sureRoute should be CUSTOM_MAP . |
ss_ |
The instant behavior is incompatible with siteShield . |
ssl_ |
In an early version of the origin behavior, origin_cert_delete is set to custom . |
ssl_ |
Due to the security risk, Akamai strongly recommends you consult with your organization’s security expert before configuring the origin SSL certificate verification settings. If you are the security expert and have any questions, contact your account team. |
ssl_ |
If you are changing your origin SSL certificate verification settings, to avoid a service outage Akamai strongly recommends testing on the staging network before activating on production. |
ssl_ |
The origin behavior has been enhanced to address the FOSSL exploit. |
ssl_ |
The origin behavior has been enhanced to address the FOSSL exploit. |
ssl_ |
An older origin version specifies a verificationMode of INSECURE . |
subrules_ |
For allowCloudletsOrigins to work, you need to nest at least one rule with a single cloudletsOrigin criteria. |
suggest_ |
Instead of redirect , consider using the edgeRedirector Cloudlet, which allows non-IT staff to manage large numbers of redirects. |
sureroute_ |
When applying instant to content whose caching is NO_STORE , the content must also have sureRoute enabled or it is not prefetched. |
tcip_ |
The origin is configured to allow clients to set the True-Client-IP header, meaning the IP value sent to the origin may not be the one the client used to connect to the edge server. While this may be useful for testing, it may allow users to bypass IP-based restrictions on your origin server. |
tcpoptisdeprecated |
The tcpOptimization behavior is deprecated, and you should remove it. |
td_ |
The tieredDistribution behavior can’t be enabled when the largeFileOptimization behavior’s useVersioning is disabled. |
td_ |
The siteShield behavior is incompatible with tieredDistribution because both determine which Akamai servers connect directly to the origin. |
third_ |
Setting the origin ’s verificationMode to THIRD_PARTY is incompatible with the specified originType . |
tiereddistribution_ |
When applying instant to cacheable content, it must also have tieredDistribution enabled or it is not prefetched. |
unpurgeable |
Enabling a behavior within a specified criteria prevents Content Control Utility from purging by URL. Contact your Akamai representative for guidance. |
urlrewrite_ |
When using removeQueryParameter , the rewriteUrl behavior’s keepQueryString must also be enabled. |
usebody |
The cachePost behavior specifies a useBody of MD5 or QUERY , but there is no accompanying cacheId . |
warn_ |
When setting denyAccess , disable the match’s useOnlyFirstXForwardedForIp to prevent malicious end users from using X-Forwarded-For headers to bypass the policy. |
warn_ |
Test any regular expressions you specify in rewriteUrl on the staging network and contact your Akamai representative if you are uncertain how to use this option. |
wildcard_ |
You should enable limitBitRate with a filename , fileExtension , or path match. |
with_ |
To apply cacheKeyIgnoreCase , you need to lowercase the elements specified by an accompanying cacheId , otherwise they never match. |
within_ |
This Cloudlet behavior may not work as expected when added to the same rule that sets the cloudletsOrigin . Consider moving it to a different rule. |
Other errors
The following may appear as standalone 400 errors:
Code | Type | Problem |
---|---|---|
400 | invalid-rule-format |
The specified rule format is not supported. Learn more. |
400 | toolkit/password-needs-rotation |
The password for the user attached to the given authorization token must be rotated. |
The following fallback error may appear when modifying a rule tree:
Type | Description |
---|---|
unknown_message |
Unknown rule tree validation error. |