Conditional Requests & Updates

The Sway Charts REST API relies on standard HTTP conditional update and request mechanism (http://en.wikipedia.org/wiki/HTTP_ETag) to ensure that:

  • No update is missed and client is always updating the latest resource version (conditional PUT and DELETE requests).

  • The client already has the latest version of the resource and there is no need to re-compute the representation again (conditional GET requests).

The Sway Charts REST API relies on the ETag/If-Match/If-None-Match HTTP headers for conditional requests.

Conditional GETs

Some GET requests to the REST API (except for collection queries) support conditions with the ETag headers according to the following algorithm:

  1. Client makes a GET request to a resource without the If-None-Match header.

  2. Server always returns a representation of the resource with an ETag header set. The ETag header uniquely and transparently identifies the version of the resource.

  3. If a resource is updated, its version is incremented and previous ETags are no longer valid.

  4. Client makes a GET request to a resource specifying the If-None-Match header with the value of previously received ETag.

  5. If ETag matches the current version on the server, the server responds with the 304 Not Modified status code and empty body. The server includes the ETag header to the response.

  6. If ETag doesn't match the current version on the server, the server responds with a new resource representation and includes the new ETag header in the response.

Conditional PUTs and DELETEs

All PUT and DELETE requests to the REST API must contain the ETag headers according to the following algorithm:

  1. Client makes a GET request to a resource without the If-None-Match header.

  2. Server always returns a representation of the resource with an ETag header set. The ETag header shall uniquely identify the version of the resource.

  3. If a resource is updated, its version is incremented and previous ETags are no longer valid.

  4. Client makes a PUT or DELETE request to a resource specifying the If-Match header with the value of previously received ETag.

  5. If ETag matches the current version on the server, the server proceeds with the request.

  6. If ETag doesn't match the current version on the server, the server responds with the 412 Precondition Failed status. Client is expected to retrieve the latest resource version and retry the request.

  7. If the client doesn't submit the If-Match header, status code of 403 Forbidden is returned along with the error details.

This prohibits "stale update" problems when there are several simultaneous updates for the same resource and one update overrides the other.

PreviousAPI VersioningNextEntity Versioning

Last updated