HTTP QUERY: Исправление API, которого мы ждали 20 лет

На протяжении десятилетий получение данных часто означало кодирование параметров поиска непосредственно в строке запроса URL GET-запроса. Этот подход быстро давал сбой при сложных поисках, включающих реляционные запросы или глубоко вложенные данные. URL-адреса разрастались, часто достигая ограничений по длине браузера или сервера, и открыто раскрывали все параметры в логах сервера и истории браузера.

Чтобы обойти ограничения URL, разработчики приняли обходное решение: использование POST-запросов для передачи сложных фильтров поиска в теле запроса. Однако это создало значительное семантическое нарушение. `POST` принципиально предназначен для создания новых ресурсов, а не для безопасного, идемпотентного получения существующих данных.

Неправильное использование `POST` для поиска имело ощутимые последствия. Оно нарушало механизмы кэширования, поскольку прокси-серверы редко кэшируют ответы `POST` из-за их неидемпотентной природы. Кроме того, его неидемпотентная характеристика не позволяла клиентам безопасно выполнять автоматические повторные попытки при сбоях сети, что является фундаментальной возможностью для операций, предназначенных только для чтения.

Менее распространенная, но не менее проблематичная попытка заключалась в отправке тела запроса с методом `GET`. Хотя спецификация HTTP/1.1 неоднозначно допускала это, она явно заявляла, что такое тело не имеет "определенной семантики" и "ДОЛЖНО игнорироваться". Это сделало "GET с телом" ненадежным, нестандартизированным мифом, так и не получившим последовательной поддержки в инфраструктуре Интернета.

Наконец, появился метод HTTP query (RFC 10008), официально стандартизированный в июне 2026 года. Он представляет собой "недостающий метод для поиска", специально созданный для устранения семантических обходных путей, которые разработчики использовали более двух десятилетий. Этот новый глагол специально предназначен для сложного получения данных только для чтения.

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

Эта гибридная конструкция напрямую решает основную проблему получения богатых данных. Разработчики теперь могут отправлять сложные, глубоко вложенные структуры запросов, такие как полезные данные JSON, в теле запроса. Это позволяет избежать превышения ограничений длины URL браузера или сервера и предотвращает раскрытие конфиденциальных параметров в логах. Что особенно важно, это устраняет семантическое нарушение использования POST для операций, не изменяющих состояние, наконец предоставляя стандартизированный, кэшируемый и семантически правильный подход для расширенного поиска в API.

`QUERY` приносит значительные операционные преимущества помимо семантической корректности, особенно в области кэширования и безопасности. Его дизайн решает давние проблемы, которые преследовали `GET` и `POST` в сценариях сложного получения данных.

Ответы, генерируемые методом `QUERY`, полностью кэшируемы, отражая эффективность `GET`. Что особенно важно, все тело запроса напрямую учитывается в ключе кэша. Этот сложный механизм гарантирует, что каждое уникальное тело запроса, независимо от URI, дает отдельную запись кэша, способствуя точному и эффективному получению данных.

Встроенный механизм обнаружения еще больше расширяет полезность `QUERY`: заголовок `Accept-Query`. Серверы теперь могут явно объявлять конкретные форматы запросов, которые они поддерживают, оптимизируя взаимодействие между клиентом и сервером и улучшая обнаруживаемость API. Клиенты получают ясность относительно ожидаемых синтаксисов, что снижает трудности интеграции.

Безопасность и конфиденциальность также значительно улучшены. `QUERY` не является CORS-safelisted method, требуя предварительного запроса `OPTIONS` для кросс-доменных вызовов и усиливая безопасность веб-приложений. Что еще более важно, он удерживает конфиденциальные параметры запроса вне URL-адресов, предотвращая их раскрытие в логах сервера, записях прокси и истории браузера, что является значительным выигрышем в конфиденциальности по сравнению с `GET`.

Этот продуманный дизайн делает `QUERY` надежным решением для современных потребностей API. Для более глубоких технических спецификаций обратитесь к RFC 10008: The HTTP QUERY Method, где подробно описаны его полные возможности и последствия для веб-архитектуры.

`QUERY` (RFC 10008) теперь официально стандартизирован, что является критически важным шагом вперед для семантики HTTP. Несмотря на это фундаментальное достижение, широкое внедрение во всей веб-экосистеме все еще находится на ранних стадиях. Браузеры, различные веб-фреймворки и сетевые прокси постепенно внедряют поддержку этого нового метода, что является длительным процессом для фундаментального изменения протокола.

Импульс явно нарастает, ключевые игроки уже интегрируют `QUERY` в свои платформы. OpenAPI 3.2 теперь официально поддерживает метод `QUERY`, позволяя архитекторам и разработчикам определять эти мощные новые конечные точки непосредственно в своих спецификациях API. Фреймворк Microsoft .NET 10 также предоставляет начальную, надежную поддержку, что является сильным сигналом для более широкой интеграции фреймворков и поощряет ранние эксперименты.

Организациям следует стратегически планировать повсеместное присутствие `QUERY` в будущем. Для новых, сложных конечных точек только для чтения проектируйте с использованием `QUERY` с самого начала, но реализуйте надежные запасные варианты на `POST` или `GET` для совместимости. Наконец, будьте готовы обновить существующие межсетевые экраны веб-приложений (WAFs) и конфигурации прокси; эти системы должны научиться правильно интерпретировать, маршрутизировать и кэшировать запросы `QUERY` для бесперебойной работы.

Что такое новый метод HTTP QUERY?

Это новый, стандартизированный HTTP-глагол (RFC 10008), разработанный для сложного поиска и извлечения данных. Он сочетает в себе безопасность и кэшируемость запроса GET со способностью передавать тело запроса, как запрос POST.

Почему бы просто не использовать GET с телом запроса?

Поведение запроса GET с телом не определено в спецификации HTTP. Это приводит к непоследовательной и ненадежной обработке серверами, прокси и кэшами, что делает его непрактичным решением.

Готов ли метод QUERY к использованию в продакшене?

Пока нет для большинства приложений. Хотя он официально стандартизирован, широкая поддержка в браузерах, серверных фреймворках и инфраструктуре, такой как прокси и WAFs, все еще находится на ранних стадиях.

Как QUERY улучшает кэширование по сравнению с использованием POST для поиска?

Ответы POST обычно не кэшируются посредниками, такими как прокси или CDNs. Ответы QUERY явно разработаны для кэширования, при этом содержимое тела запроса используется как часть ключа кэша, что значительно улучшает производительность.