The Property Manager API

The Property Manager API (a.k.a. PAPI) offers a programmatic OPEN 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 documentation on 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 the OPEN API Introduction 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 Open API Provisioning to create your OPEN 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 {OPEN} 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.)

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

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

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

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

Renaming Features and Options

The current API release is part of an effort to standardize PAPI’s catalog of features. This section summarizes the range of changes and what you need to do to adapt to them.

The first set of changes renamed behaviors and criteria to conform to standard camelCase, and overall made them more readable and consistent. The Behaviors and Criteria references both list the previous set of non-standard names. Following this change, the API will continue to accept the old, non-standard feature names when writing a rule tree. However, PAPI will always respond with updated feature names on subsequent read operations, so any code that assumes the older set of names breaks at that point. Any older feature_name that you write will always be read back as featureName.

The second wave of changes modified features’ component options, in several ways:

  • Option names are standardized around camelCase, and made more consistent and readable.

  • Option string enumeration values are standardized around UNDERSCORE_DELIMITED_ALL_CAPS and made more readable.

  • Most two-state enumerations are retyped, so the previous inconsistent set of "true"/"false", "on"/"off", and "yes"/"no" string values standardize around true/false boolean values.

  • Some conceptually numeric option values previously represented as a quoted string are retyped as numeric, so for example certain string representations of HTTP codes, port numbers, and numeric timing values may need to change.

All these changes are listed throughout the Behaviors and Criteria references.

Note that with these various changes to options, PAPI does not passively accept the old values as it does for feature names. Instead, PAPI’s rule formats feature provides a formal upgrade path. Use this procedure:

  1. First, you get the most recent ruleFormat version string.

  2. You then use that version string to freeze the rule tree’s set of features. This prevents rules from automatically upgrading to newer options as they become available. (Even if you are not planning to update options, you should implement these first two steps to make sure your set of features is frozen.)

  3. When a new rule format becomes available, check again for the more recent ruleFormat version string.

  4. Follow the instructions to Update Rules to a Newer Set of Features, invoking the new version string within the Accept and Content-Type headers’ MIME types as described.

The final step forces options to convert to the new rule format. You can use this approach to update to a newer version, but not to downgrade to an older version. As noted in the update instructions, some changes to option values may not convert smoothly, and will yield errors as detailed in the Debug section. The majority of straightforward changes to option names, option enumeration values, and boolean types should convert smoothly.

NOTE: The current PAPI release’s v2016-11-15 rule format freezes the set of changes described above, so you should upgrade to that rule format.