API

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. This versioning refers to the core PAPI operations, which you can view in the API summary section.

  • The catalog rule formats within our API are versioned independently from the core API operations. ​Akamai​ often modifies the catalog of behaviors and criteria, each time deploying a new internal version of the feature. To allow new features to roll out without incrementing the core API’s version, PAPI supports a system of versioned objects called rule formats. PAPI versions schema objects as a whole and creates dated snapshots for the set of features available within a property's rule tree. When exchanging data, you use Accept and Content-Type headers to specify these custom versioned MIME types. New rule formats may include breaking changes, unlike the core API operations that maintain consistent backward and forward compatibility. Each rule format version is an integral part of the API contract, so you should adhere to industry standards and best practices when interacting with these versions.

  • Dynamic rule updates. We support backward compatibility to PAPI, allowing you to consistently use the latest rule format without managing breaking changes due to the catalog updates. You can send their previous inputs, which are processed successfully even if the catalog has been updated. PAPI converts these inputs to the newer format, ensuring seamless integration and operation. Learn more about Dynamic rule updates.

  • You can freeze and update the rule format that defines the version of the features you use in your property's rules. Each behavior and criteria you invoke within your rules may independently increment versions from time to time, but you can only specify the most recent dated rule format to freeze the set of features. Otherwise, if you assign the latest rule format, features update automatically to their most recent version. This may abruptly result in errors if JSON in your rules no longer comply with the most recent feature's set of requirements.

📘

Once you've frozen a rule format in PAPI, that state persists even if you use the Property Manager interface in Control Center. You no longer get any feature upgrade prompts.

  • The most recent set of features is detailed in the behavior and criteria reference. For information on features specified by older rule formats, see Deprecated rule formats.

  • PAPI lets you access your own sets of property versions or include versions. Versions are available as URL resources that you can modify and activate independently, or perform roll-back if needed. These sets are the only versioned object under your direct control.

  • The API's Build interface also provides details on the current software release 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. Don't rely on any of the internal version numbers this interface makes available.

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