Метод HTTP QUERY

QUERY — предлагаемый метод HTTP, закрывающий реальный пробел: он безопасный и идемпотентный, как GET, но при этом может нести тело запроса, как POST. Считайте его «GET, вместе с которым можно отправить полезную нагрузку».

Зачем он существует

Сложные запросы издавна вынуждали делать неудобный выбор:

• GET со строкой запроса помещает каждый фильтр в URL. У URL есть ограничения на длину, они попадают в журналы в открытом виде и неуклюжи для структурированных или вложенных условий.
• POST с телом прекрасно несёт полезную нагрузку, но лжёт о намерении. POST не является ни безопасным, ни идемпотентным, поэтому кэши, краулеры и промежуточные узлы вынуждены считать, что запрос изменяет состояние. А он не изменяет — вы просто читаете.

QUERY снимает это противоречие: семантика говорит «это чтение», а тело несёт условия выборки.

Свойства

Как выглядит запрос

QUERY /products HTTP/1.1
Host: shop.example
Content-Type: application/json
Accept: application/json

{ "category": "boots", "inStock": true }

Кэширование с помощью Content-Location

Поскольку QUERY безопасен и идемпотентен, ответ можно кэшировать — но ключом кэша не может быть один лишь URL, ведь тело меняется. Сервер указывает каноническое расположение результата заголовком Content-Location:

HTTP/1.1 200 OK
Content-Location: /products?category=boots&inStock=true
Cache-Control: max-age=60

Кэш (или клиент) затем может переиспользовать это представление для эквивалентного запроса. Именно этот механизм позволяет чтению с телом оставаться кэшируемым.

Попробуйте сами

Загляните в Песочницу и отправьте настоящий запрос QUERY на эхо-эндпоинт этого сайта, чтобы в точности увидеть, как метод, заголовки и тело доходят до сервера.

QUERY определён в IETF Internet-Draft и всё ещё развивается. Считайте приведённые выше подробности рабочей выжимкой и сверяйтесь со связанным черновиком как с авторитетным и актуальным текстом.