The Property Manager API v0

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 the Luna 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.

What’s In This Guide

This guide is arranged as follows:

  • This Overview helps you get set up with the API’s initial requirements, introduces you to the many concepts you’ll need to know, and details various API conventions.

  • The Rules section provides guidance on how to structure rule trees. It discusses how to manipulate variables and invoke them throughout the rule tree. It also shows useful information you can get from a rule format schema.

  • The Behaviors and Criteria sections provide a full specification for all the features you can include as part of a property’s rules. (These specify the most recent set of features. See API Versioning below for older feature sets.)

  • The Debug section shows you how to deal with errors and warnings you may likely encounter when modifying rules, and shows how to respond to runtime errors with variables. It details the range of potential errors the API may produce, and notes known limitations in the current API release.

  • The Data section specifies the API’s data model, detailing how the JSON objects for each resource are structured.

  • The Resources section specifies the API’s resource model, detailing each API operation, and provides comprehensive details of the API workflow.

This Overview discusses the following topics:

  • Getting Started tells what you need to know before you start using this API.

  • PAPI Concepts provides an overview of the API’s conceptual elements, and how they relate to API interfaces. Read this if you need a high-level overview of what PAPI and the Property Manager do.

  • Data Conventions details the API’s common set of JSON member naming conventions.

  • Rate and Resource Limiting tells you how to detect any limits on the number of objects you can create, or the frequency with which you can deploy new properties.

  • Concurrency Control details the system that can prevent more than one client from mistakenly overwriting the same data.

  • API Versioning clarifies the separate version numbers applied to the API, the catalog of features, and the software build.

  • Renaming Features and Options provides you with strategies to adapt to a series of changes to feature names, option names, option types, and enum values.

Getting Started

Before using PAPI for the first time:

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

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

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

  • Review the API’s Known Issues.

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

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

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

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

PAPI Concepts

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

  • Accounts: Akamai customers access all their services via an account key. While administrators may have access to more than one account, in general they provision all their web assets under a single account within the Akamai Luna portal. 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 the Luna portal 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 the Luna interface’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 Rules 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 Criteria Reference for information on all criteria the API makes available, and see the Rules 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 Behaviors Reference for information on all behaviors the API makes available, and see the Rules section for instructions on how to arrange them within JSON payloads.)

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

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

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

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

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

  • Rule Formats: You use rule formats to freeze or update the versioned set of behaviors and criteria a rule tree invokes. (Without this mechanism, behaviors and criteria would update automatically and generate unexpected errors.) PAPI tracks rule formats in a database keyed by rule format version date strings. These reference rule format schema objects, which specify the full set of behaviors and criteria available for a given product and the set of modules it may enable, as well as their allowed options and option values. (See the operations to List Rule Formats and Get a Rule Format’s Schema. See also the operations that list currently available behaviors and criteria.)

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

Properties also include hostnames:

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

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

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

API Versioning

The API exposes several different versioning systems:

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

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

    Reference documentation for the latest set of features is available in the Behaviors and Criteria sections. For documentation 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 than version.

PAPI applies the following JSON member naming conventions:

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

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

    • act_ prefix for accountId
    • ctr_ prefix for contractId
    • grp_ prefix for groupId
    • prd_ prefix for productId
    • prp_ prefix for propertyId
    • ehn_ prefix for edgeHostnameId
    • hst_ prefix for hostnameId
    • atv_ prefix for activationId
    • msg_ prefix for messageId
    • cpc_ prefix for cpcodeId
  • *Date members represent date-time in ISO 8601 format using UTC timezone (such as updateDate). The API names all timestamps as *Date, they all use this same format.

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

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

Rate and Resource Limiting

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

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

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

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

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

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

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

PAPI reports the following set of contextual HTTP headers:

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

Concurrency Control

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

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

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

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

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

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

PAPI provides several other ways to use this mechanism:

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

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

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

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

Validation and Activation Time

PAPI’s most important function is to modify rule trees associated with sets of hostnames, and to activate them on the edge. As described in the Rules 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:

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.


Last modified: 5/24/2017