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