Version resources with ETags#

Use this guide to keep a modification from overwriting one made in between, and to skip a download that would bring back a resource unchanged. Both rest on the HTTP entity tags RFC7644 ยง3.14 binds to the meta.version attribute of a resource.

Nothing has to be configured. A client that has read the ServiceProviderConfig of a server advertising ETag support sends the conditional headers on its own, and sends none when the server does not advertise it or when the resource at hand carries no version.

Note

The client only learns of that support once it has read the ServiceProviderConfig, either with discover() or by passing it in the provider describing the server.

Refuse a write that would overwrite a change#

replace(), modify() and delete() send an If-Match header built from the version of the resource they are given. The server returns 412 Precondition Failed when the resource changed since it was read, which is the optimistic concurrency control the specification describes:

from scim2_models import SCIMException

scim.discover()

# The version is read from the server response
user = scim.query(User, "my-user-id")

# If-Match is sent automatically
user.display_name = "Updated Name"
try:
    user = scim.replace(user)
except SCIMException as exc:
    if exc.status == 412:
        print("The resource has changed, read it again")
    else:
        raise

# If-Match is sent automatically here too
scim.delete(user)
from scim2_models import SCIMException

await scim.discover()

# The version is read from the server response
user = await scim.query(User, "my-user-id")

# If-Match is sent automatically
user.display_name = "Updated Name"
try:
    user = await scim.replace(user)
except SCIMException as exc:
    if exc.status == 412:
        print("The resource has changed, read it again")
    else:
        raise

# If-Match is sent automatically here too
await scim.delete(user)

The version is read from the ETag response header, or from the meta.version attribute when the server fills it. A write aimed at a resource the client never read carries no header, since it is the server that assigns the version.

Skip a download that would change nothing#

Reads are conditional too. query() sends an If-None-Match header when it is given a versioned resource object. The server returns 304 Not Modified when the resource did not change, nothing is downloaded, and the object that was passed is returned:

user = scim.query(User, "my-user-id")

# If-None-Match is sent; 'fresh' is 'user' itself on a 304
fresh = scim.query(user)
user = await scim.query(User, "my-user-id")

# If-None-Match is sent; 'fresh' is 'user' itself on a 304
fresh = await scim.query(user)

Warning

On a 304 Not Modified the very object that was passed is returned, not a copy. Local modifications made to it are therefore given back as if they came from the server.

No If-None-Match is sent when query_parameters are used, since the server would then answer a partial representation that the cached object cannot stand for.