Conflict Detection with Qumulo's REST API

IN THIS ARTICLE 

Provides an overview of conflict detection with Qumulo's REST API

REQUIREMENTS

• IP Address or URL for cluster running Qumulo Core
• Utility or method for placing API calls (Curl)
• Access to API & Tools page for reference

DETAILS

Many of our configuration endpoints have straightforward behavior. You can use GET to retrieve a document (e.g. GET /v1/users/123) and use PATCH to update the document. The requests take effect immediately so that when you receive a 200 OK response, you know the change has been made. But REST is not transactional when it comes to making changes, which can impact the user experience if not considered properly. With our conflict detection scheme, clients are able to query resources to find out if they’ve changed since the last access time. Resources have a unique tag describing their current value, which is represented in HTTP 1.1 by an entity tag (ETag).

The API leverages the HTTP ETag mechanism to handle concurrent resource modifications. We return an ETag containing a version string for each versioned resource. If conflict detection is desired, the caller should provide an If-Match header containing the ETag associated with the expected resource version.

The flow for modifying a resource is as follows:

• Client requests the current representation of a resource with a GET request. Response includes an ETag header.
• Client sends an update for that resource with a PATCH, PUT or DELETE request. The request includes an If-Match header with the previously received ETag value.
• If the resource’s current ETag is the same as the If-Match value, the request succeeds with a 2xx response. Otherwise, the request fails with a 412 Precondition Failed response.
• Upon receiving a 412, the client can GET the resource again and automatically retry the operation, or inform the user of the underlying change and confirm that they want to proceed.

Let’s say an administrator is editing a file share on the cluster using the Interactive API in API & Tools. Between the time the UI retrieves the file share details and when the administrator saves their changes, another user or process could change that file share. By default in our API, the last writer wins so the administrator would unwittingly clobber these changes. That’s not the user experience we want, so we use ETag and If-Match HTTP headers for all of our documents to prevent accidental overwrites.

When the UI retrieves a document, it reads the ETag response header (entity tag or essentially a hashcode) and stores that. Later, when updating that same document, the UI sends an If-Match request header which tells the cluster to only perform the action if the document is the same as we expect. If the document changed, we’ll get back a 412 Precondition Failed response which allows us to build a better experience for the user.

RESOLUTION 

You should now have an overall understanding of conflict detection with Qumulo's REST API

ADDITIONAL RESOURCES

Getting Started with Qumulo Core REST API

Authentication with Qumulo's REST API

Qumulo's GitHub Open Source Community

Like what you see? Share this article with your network!