Специальные заголовки

X-Delta

Заголовок используется для указания версий дельты в запросе. Значение заголовка должно содержать обозначение версий дельты. В ответе название конечной версии должно быть указано в заголовке «Content-Version». Версия в ответе должна быть указана явно, т.е. без слова last.

Пример использования (можно указывать как v0.6, так и v0.7):

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

> X-Delta: v0-last

> ...

< HTTP/1.1 200 OK

< Content-Version: "delta v0-v6"

< ...

< [[1, "Апельсин"]]

Content-Version (API v0.7)

Заголовок содержит название конечной версии кэша. «Content-Version» должен всегда отправляться в ответе (не только для дельты, но и для полной таблицы), если ресурс кэшируемый.

Пример использования:

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

> ...

< HTTP/1.1 200 OK

< Content-Version: v2

< ...

Х-Data-Range

Заголовок «X-Range» работает так же как Range, кроме следующих моментов:

данные усекаются до архивации;
не поддерживается указание нескольких диапазонов.

Пример заголовков в запросе и ответе:

Запрос

Ответ

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

Если в запросе передан заголовок «X-Device-Id», то в случае успешной аутентификации в базе данных будет создано устройство (если оно не было создано ранее) и привязано к текущему пользователю.

CORS

Если в запросе указан заголовок «Origin», то включается совместное использование ресурсов между разными источниками. В ответе на такой запрос содержится заголовок «Access-Control-Allow-Origin: *», означающий, что принимаются запросы любого происхождения.

Сервер поддерживает заголовок «Access-Control-Expose-Headers» для всех запросов API. Сервер возвращает заголовки «Access-Control-Allow-Headers», «Access-Control-Allow-Methods» для метода OPTIONS.

CORS заголовки не поддерживаются для web/webdav ресурсов (или поддерживаются целевым сервером).

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

Для контроля актуальности кэша ресурса разработчик может использовать заголовок «If-Match». В ответ сервер должен отдавать «Etag», где «Etag» - уникальный идентификатор, который генерируется сервером и изменяется каждый раз, когда запрашивается контент. Таким образом, «Etag» является валидатором, где явно сообщается актуальность кэша.

Существует два распространенных варианта использования:

для методов GET и HEAD-методов, используемых в сочетании c RANGE, он может гарантировать, что запрашиваемые новые диапазоны с того же ресурса, что и предыдущий. Если он не соответствует, то возвращается ответ 416 (Range Not Satisfiable).
для других методов и, в частности, для PUT-методов, «If-Match» может использоваться для предотвращения проблемы с потерянным обновлением. Он может проверить, не изменит ли изменение ресурса, которое пользователь хочет загрузить, другое изменение, которое было выполнено с момента извлечения исходного ресурса. Если запрос не может быть выполнен, возвращается ответ 412 (Precondition Failed).

Для того, чтобы узнать изменен ли кэш ресурса с момента его последнего просмотра, разработчик может использовать заголовок «If-Modified-Since».

Заголовок «If-Modified-Since» делает запрос условным: сервер отправит обратно запрошенный ресурс с статусом 200, только если он был последним изменен после указанной даты. Если запрос не был изменен с тех пор, ответ будет 304. Заголовок «Last-Modified» будет содержать дату последней модификации. В отличие от «If-Unmodified-Since», «If-Modified-Since» может использоваться только с GET и HEAD-методами.

В случае, если необходимо узнать, совпадает ли кэш ресурса, то может использоваться заголовок «If-None-Match»: если ETag совпадают по результатам запроса «If-None-Match», то кэш ресурса совпадает.

Заголовок «If-None-Match» делает запрос условным: сервер отправляет обратно запрошенный ресурс с статусом 200, только если он не имеет «Etag» соответствующих данных, когда используются GET и HEAD-методы. Для других методов запрос будет обрабатываться только в том случае, если в конечном итоге существующий ресурс «Etag» не соответствует ни одному из перечисленных значений. Если условие не выполняется с GET и HEAD-методами, то сервер возвращает код статуса: 304. Если запрос не может быть выполнен, то возвращается ответ 412 (Precondition Failed).

Существует два распространенных варианта использования:

для GET и HEAD-методов, для обновления кэшированного объекта, который связан с ним «ETag»;
для других методов, например, PUT-метода, если «If-None-Match» используется для сохранения неизвестного файла.

Пример использования:

Запрос

Ответ

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

См. также:

API сервера | Обозначение версий дельты в запросах