Special Headers

X-Delta

A header is used to specify delta versions in a request. Header value must contain delta version designation. The response must contain end version name in the Content-Version header. The response must have an explicitly specified version, that is, without the word "last".

Example of use (the version can be specified both as v0.6 and v0.7):

> GET /api/v0.6/table/fruits

> X-Delta: v0-last

> ...

< HTTP/1.1 200 OK

< Content-Version: "delta v0-v6"

< ...

< [[1, "Orange"]]

Content-Version (API v0.7)

The header contains name of cache end version. The Content-Version header must always be sent to in the response (not only for delta, but for full table), if the resource is cacheable.

Example of use:

> GET /api/v0.7/table/fruits

> ...

< HTTP/1.1 200 OK

< Content-Version: v2

< ...

X-Data-Range

The X-Range header works identically as Range, except for the following features:

Data is truncated before archiving.
It does not support specifying several ranges.

The example of headers in request and response:

Request

Response

Accept-Encoding: gzip

X-Range: bytes=123-

If-Match: "1a2b3c"

Content-Encoding: gzip

Content-Range: bytes 123-/*

ETag: "1a2b3c"

Trunsfer-Encoding: chunked

X-Device-Id

If the request contains the X-Device-Id header, after successful authentication a device is created in the database (if it has not been created before) and linked to the current user.

CORS

If the request contains the Origin header, shared use of resources between different data sources is enabled. The response to this request contains the Access-Control-Allow-Origin: * header that means that any requests are accepted.

The server supports the Access-Control-Expose-Headers header for all API requests. The server returns the Access-Control-Allow-Headers, Access-Control-Allow-Methods headers for the OPTIONS method.

CORS headers are not supported for web/webdav resources (or are supported by target server).

If-Match, If-Modified-Since, If-None-Match

To control whether resource cache is actual, the developer can use the If-Match header. The server response must contain Etag that is a unique identifier generated by the server and is changed each time contents is requested. Therefore, Etag explicitly validates whether cache is actual.

There are two popular options of use:

For GET and HEAD methods used together with RANGE, it can guarantee that requested new ranges are from the same resource that the previous one. If it does not match, 416 (Range Not Satisfiable) is returned.
For other methods, and particularly, for PUT methods, If-Match can be used to prevent the issue with lost update. It can check if the resource change, which the user wants to load, changes the other change executed since the source resource has been extracted. If the request cannot be executed, 412 (Precondition Failed) is returned.

To know whether resource cache has been changed since its last view, the developer may use the If-Modified-Since header.

The If-Modified-Since header makes the request conditional: the server sends back the requested resource with the 200 state, only if it was the last to be changed after the specified date. If the request has not been changed since then, the response contains 304. The Last-Modified header contains the date of the last modification. Unlike If-Unmodified-Since, If-Modified-Since can be used only with GET and HEAD methods.

If it is required to know whether resource cache matches, the If-None-Match header can be used, if ETag match by If-None-Match request results, resource cache matches.

The If-None-Match header makes a request conditional: the server sends back the requested resource with the 200 status only if it does not have Etag of corresponding data when GET and HEAD methods are used. For other methods, the request is handled only if the final total contains the Etag resource that does not correspond to none of the given values. If a condition is not satisfied with GET and HEAD methods, the server returns status code 304. If the request cannot be executed, the 412 (Precondition Failed) response is returned.

There are two popular options of use:

For GET and HEAD methods, to refresh the cached object linked with it by ETag.
For other methods, for example, PUT method if If-None-Match is used to save the unknown file.

Example of use:

Request

Response

If-Match: "1a2b3c"

If-Modified-Since: <day-name>, <day> <month> <year> <hour>:<minute>:<second> GMT

If-None-Match: "737060cd8c284d8af7ad3082f209582d"

ETag: "1a2b3c"

Trunsfer-Encoding: chunked

304 Not Modified

200 OK