# 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 `ETag`s 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.