Método HTTP QUERY: la nueva forma de consultar APIs

El IETF HTTP Working Group está finalizando un nuevo método HTTP llamado QUERY, definido en el draft «The HTTP QUERY Method» (draft-ietf-httpbis-safe-method-w-body), con última versión publicada el 23 de junio de 2026 y autores Julian Reschke, James M. Snell (Cloudflare) y Mike Bishop (Akamai).

El objetivo es simple pero importante: resolver un problema que cualquier desarrollador backend conoce de memoria. Hasta ahora, para hacer consultas complejas a una API había que elegir entre dos males:

• GET con query string: es seguro e idempotente, pero tiene límites prácticos de tamaño (la spec de HTTP recomienda soportar al menos 8000 octetos), se loguea en cualquier lado, y no escala bien para filtros complejos.
• POST con body: permite mandar cualquier volumen y estructura de datos, pero no es seguro ni idempotente por definición, así que ni los navegadores ni los proxies ni los cachés pueden asumir que es repetible sin riesgo.

QUERY llena ese hueco: te deja mandar contenido en el body de la request (como POST) pero garantizando que la operación es segura e idempotente (como GET).

El problema que viene a resolver

El propio draft lo resume con una tabla comparativa entre GET, QUERY y POST. Tres cosas determinan si una operación es «segura»: que el cliente no espere cambios de estado en el servidor, que se pueda cachear, y que se pueda reintentar sin miedo a duplicar efectos.

POST falla en eso porque, semánticamente, «podría» modificar estado del lado del servidor. El navegador no tiene forma de saber si tu endpoint /buscar-productos hecho con POST es en realidad de solo lectura o si dispara un proceso con efectos secundarios. Por eso POST nunca se cachea de forma automática ni se reintenta solo ante un fallo de conexión.

Con QUERY, el contrato es explícito: el servidor declara que esa ruta es de solo lectura, así que clientes, proxies y CDNs pueden tratarla como tratarían un GET, pero con la flexibilidad de un body arbitrario.

Cómo se usa: ejemplo básico

El patrón típico de búsqueda con GET se ve así:

GET /feed?q=foo&limit=10&sort=-published HTTP/1.1
Host: example.org

Cuando los parámetros no entran cómodos en una URL, hoy se suele recurrir a POST:

POST /feed HTTP/1.1
Host: example.org
Content-Type: application/x-www-form-urlencoded

q=foo&limit=10&sort=-published

Con QUERY, la misma operación queda así, explicitando que es una consulta segura e idempotente:

QUERY /feed HTTP/1.1
Host: example.org
Content-Type: application/x-www-form-urlencoded

q=foo&limit=10&sort=-published

El método no impone un formato de body: puede ser application/x-www-form-urlencoded, JSON, SQL, JSONPath, XSLT o cualquier media type que el servidor decida soportar. La semántica de la consulta depende exclusivamente del contenido y de su Content-Type.

La cabecera Accept-Query

El draft también define un nuevo header de respuesta, Accept-Query, que le permite a un servidor anunciar qué formatos de consulta soporta en un recurso determinado:

HTTP/1.1 200 OK
Content-Type: application/xhtml
Accept-Query: application/x-www-form-urlencoded, application/sql

Esto es útil para descubrimiento de capacidades vía OPTIONS o HEAD, sin tener que probar a ciegas qué formato acepta cada endpoint.

Recurso equivalente, Location y Content-Location

Una parte interesante de la propuesta es el concepto de «equivalent resource»: el servidor puede asignarle una URI propia a una consulta QUERY específica (vía el header Location) o a su resultado puntual (vía Content-Location). Esto habilita algo muy práctico: una vez que el servidor te da esa URI, podés repetir la consulta haciendo un simple GET, sin reenviar el body completo cada vez, y aprovechar validadores como ETag o Last-Modified para requests condicionales y respuestas 304 Not Modified.

Esto también simplifica el cacheo: cachear una respuesta a GET es trivial porque la URL es la clave. Cachear QUERY es más complejo porque la clave de caché tiene que incorporar el contenido completo del body (y su Content-Type), tal como indica el draft en la sección de caching apoyándose en RFC 9111.

Códigos de estado y manejo de errores

El draft es bastante específico sobre cómo responder ante distintos tipos de error:

• 400 Bad Request: falta el Content-Type, o es inconsistente con el contenido real del body.
• 415 Unsupported Media Type: el Content-Type es válido pero el recurso no lo soporta para QUERY (acá entra en juego Accept-Query para informar alternativas).
• 422 Unprocessable Content: el formato es correcto y soportado, pero la consulta en sí no se puede ejecutar (por ejemplo, SQL sintácticamente válido que apunta a una tabla que no existe).
• 406 Not Acceptable: el cliente pidió, vía Accept, un formato de respuesta que el servidor no puede generar.

Seguridad y consideraciones para CORS

El documento dedica una sección a seguridad que vale la pena tener presente si pensás exponer QUERY en una API pública:

• QUERY es preferible a GET cuando la consulta contiene información sensible, justamente porque evita que esos datos terminen en la URL (y por lo tanto en logs, historiales de navegador o caches de proxies intermedios).
• Si el servidor crea un recurso temporal para el resultado (Location o Content-Location), esa URI no debería contener información sensible del request original.
• QUERY no pertenece a la lista de métodos «CORS-safelisted» del Fetch Standard, así que cualquier llamada cross-origin a un endpoint QUERY desde el navegador va a disparar un preflight OPTIONS antes de la request real. Esto es relevante para quien ya viene lidiando con configuración de CORS en sus APIs.

¿Por qué no reusar PROPFIND, REPORT o SEARCH?

El registro de métodos HTTP ya tenía tres métodos «safe» e idempotentes: PROPFIND, REPORT y SEARCH, todos originados en el ecosistema WebDAV. El draft explica en su apéndice por qué no se optó por reutilizarlos: esos métodos están atados a un media type genérico de WebDAV (XML), cargan con el bagaje histórico de esa especificación, y «QUERY» comunica mejor la relación conceptual con el componente de query de una URI.

Qué significa esto en la práctica para tu stack

Si trabajás con APIs REST en Laravel, CodeIgniter o Node.js, el método QUERY todavía no tiene soporte nativo amplio en frameworks ni en navegadores (es un Internet-Draft, no un RFC publicado), pero conviene tenerlo en el radar por varias razones:

• Endpoints de búsqueda y reporting con filtros complejos podrían dejar de depender de POST «disfrazado de GET», ganando cacheabilidad real.
• CDNs y reverse proxies como Traefik eventualmente van a poder cachear estas consultas de forma nativa, algo que hoy es prácticamente imposible con POST.
• Para integraciones tipo GraphQL o motores de búsqueda internos, QUERY ofrece una semántica HTTP más honesta que forzar todo a POST.

Por ahora, sigue siendo un draft en estado «Standards Track» con fecha de expiración (25 de diciembre de 2026), así que todavía puede sufrir cambios antes de convertirse en RFC. Vale la pena seguir el repositorio del grupo de trabajo HTTP en GitHub para no perderse la versión final.

El método QUERY resuelve un problema real y viejo del protocolo HTTP: la falta de un método seguro e idempotente que acepte un body arbitrario. No reemplaza a GET ni a POST, sino que cubre el espacio que quedaba entre ambos. Si tu trabajo incluye diseño de APIs, este es uno de esos cambios «de bajo perfil» en la especificación HTTP que conviene entender antes de que llegue a los frameworks y a los navegadores.

Fuente: https://httpwg.org/http-extensions/draft-ietf-httpbis-safe-method-w-body.html