Заголовок HTTP Prefer позволяет клиентам указывать предпочтения относительно определённого поведения сервера при обработке запроса.

Синтаксис

Prefer: <preference>, <preference>, ...

Директивы

respond-async

Клиент предпочитает асинхронную обработку. Например, сервер может отправить ответ 202 Accepted, указывающий, что запрос принят, а также заголовок Location с URL, который клиент может использовать для отслеживания состояния обработки.

return=minimal

Запрашивает у сервера минимальное содержимое (ответ только с заголовками).

return=representation

Запрашивает полное представление ресурса в ответе.

wait=<seconds>

Время, в течение которого клиент ожидает получить ответ от сервера с момента получения запроса. Если также указано предпочтение respond-async, сервер должен ответить асинхронно, если обработка запроса займёт больше времени, чем указанный период ожидания. В противном случае серверу следует исходить из того, что время ожидания клиента истечёт по истечении wait (поведение ответа зависит от реализации сервера).

handling=lenient

Клиент хочет, чтобы сервер применял при обработке запроса нестрогую проверку и обработку ошибок.

handling=strict

Клиент хочет, чтобы сервер применял при обработке запроса строгую проверку и обработку ошибок.

Пользовательское предпочтение

Поставщики или приложения могут определять собственные предпочтения для решения конкретных задач. Например, Prefer: timezone=America/Los_Angeles.

Примеры

Запрос минимального ответа

Следующий запрос требует минимальный ответ. Обычно это ответ только с заголовками (в отличие от return=representation, когда в теле ответа содержится представление ресурса):

POST /resource HTTP/1.1
Host: example.com
Content-Type: application/json
Prefer: return=minimal

{"id":123, "name": "abc"}

Сервер отвечает статусом 201, но не включает тело ответа. Заголовок Location содержит URL расположения созданного ресурса. Добавлять заголовок Preference-Applied не требуется, поскольку отсутствие тела ответа очевидно:

HTTP/1.1 201 Created
Location: /resource?id=123

Запрос асинхронной обработки

В этом примере запрашивается запуск сервером задачи асинхронной обработки:

POST /process HTTP/1.1
Host: example.com
Prefer: respond-async

{
  "task": "check-broken-links"
}

Сервер отправляет ответ 202 Accepted, указывающий, что запрос принят, но его асинхронное выполнение ещё не завершено. Заголовок Location указывает на монитор состояния, отражающий ход обработки:

HTTP/1.1 202 Accepted
Location: http://example.com/tasks/123/status

Указание нескольких предпочтений

Следующий запрос содержит два предпочтения: timezone=Jupiter/Red_Spot указывает предпочтительный часовой пояс клиента, а handling=strict — на строгую проверку:

GET /events HTTP/1.1
Host: example.com
Prefer: handling=strict, timezone=Jupiter/Red_Spot

В этой реализации недопустимый часовой пояс вызывает ошибку:

HTTP/1.1 400 Bad Request

Спецификации

См. также

• Preference-Applied
• Заголовок Prefer на docs.oasis-open.org
• Заголовок Prefer на docs.postgrest.org