QUERY: новый метод для передачи параметров в теле GET запроса

IETF утвердила новый HTTP-метод под названием QUERY. Он получил статус «предложенного стандарта» и описан в документе RFC 10008. Метод закрывает проблему, которая долгие годы мучила разработчиков API: как отправлять сложные запросы с параметрами в теле запроса, сохраняя при этом все преимущества GET.

POST не подходит для запросов на чтение:

Раньше приходилось использовать POST для передачи параметров в теле - это работало, но нарушало семантику, потому что POST предназначен для изменения данных, а не для чтения. И главное - POST-запросы не кэшируются CDN и прокси-серверами. Каждый раз сервер получает новый запрос и обрабатывает его, даже если параметры и результаты не менялись. Это создает лишнюю нагрузку на бэкенд.

GET не подходит для сложных запросов:

GET с параметрами в URL кэшируется, но имеет ограничение по длине и не подходит для сложных структур. Получался выбор: либо кэширование и ограничения, либо без кэширования и без ограничений.

Решение - QUERY:

QUERY наконец-то дает официальное решение: параметры в теле, как у POST, но при этом кэширование и безопасность повторения, как у GET.

Как это работает:

Новый метод QUERY работает так же, как POST - параметры передаются в теле запроса. Но при этом он безопасный и идемпотентный, как GET. Это значит, что его можно повторять без опасений, кэшировать ответы и использовать в сетях с ненадежной связью.

Пример запроса:


Метод явно говорит серверу, прокси и CDN: это запрос данных, он не меняет состояние ресурса, его можно безопасно повторить, а ответ может быть закэширован.

Как проверить поддержку QUERY:

QUERY поддерживается не всеми серверами. Но есть стандартные способы проверить это. Самый простой - использовать OPTIONS:


В ответе сервер вернет список поддерживаемых методов в заголовке Allow:


Еще один способ - отправить QUERY-запрос и посмотреть на ответ. Если сервер вернет 405 (Method Not Allowed), значит метод не поддерживается.

Какие форматы запросов поддерживаются:

Метод QUERY не привязан к конкретному формату. Тело запроса может быть отправлено в разных форматах. В спецификации упоминаются application/x-www-form-urlencoded, JSONPath, XSLT и даже SQL. Сервер сообщает о поддерживаемых форматах через заголовок Accept-Query.

Это позволяет использовать наиболее подходящий формат для конкретной задачи.

Кэширование и производительность:

QUERY поддерживает кэширование через стандартные HTTP-механизмы. Ответ можно кэшировать и использовать для последующих запросов с теми же параметрами. Клиенты могут использовать Conditional Requests (If-Modified-Since, If-None-Match) для проверки актуальности данных.

Также сервер может вернуть заголовки Content-Location или Location, указывающие на URI, по которому можно получить результат через GET. Это позволяет переключиться на более эффективный GET для повторяющихся запросов.

Когда это пригодится:

Метод QUERY особенно полезен для сложных API-запросов с большим количеством параметров. Графики, аналитика, полнотекстовый поиск, сложные фильтры, работа с большими объемами данных - все это теперь можно делать без компромиссов.

Конфиденциальные данные тоже не будут попадать в логи сервера, потому что они передаются в теле запроса, а не в URI.

Вывод:

QUERY закрывает пробел между GET и POST, который существовал десятилетиями. Это безопасный, идемпотентный метод с поддержкой тела запроса и кэширования.

Пока рано ждать повсеместного внедрения - стандарт совсем свежий. Пройдет еще какое-то время, прежде чем его начнут поддерживать серверы, библиотеки и прокси. Но для тех, кто проектирует новые API, этот метод стоит взять на заметку. Особенно если предстоит работать со сложными поисковыми запросами или большими объемами данных.