API
TrainingSupportCommunity

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:

  • An etag object member.

  • The double-quoted contents of the Etag HTTP header.

When performing any subsequent PUT, PATCH, or DELETE write operation, or when calling POST to clone a property, provide the same data as either of these:

  • 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 Property Manager interface.

📘

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 offers 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 haven't 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 haven't 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.

📘

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