Método HTTP QUERY explicado: RFC 10008, QUERY vs GET vs POST

El método HTTP QUERY es un nuevo método de solicitud, definido en el RFC 10008 (junio de 2026), que envía una consulta en el cuerpo de la solicitud y es tanto seguro como idempotente. Piénsalo como GET con cuerpo: obtienes el espacio de POST para filtros complejos y las garantías de GET para el almacenamiento en caché y los reintentos automáticos.

Si has metido un filtro de 3 KB en una URL, o has enviado una búsqueda de solo lectura como POST y has visto que tu caché y tu lógica de reintentos lo ignoran, QUERY es la solución. Esta guía cubre lo que dice la especificación, cómo se compara QUERY con GET y POST, qué lo admite hoy y cómo probar un endpoint QUERY con tu agente de programación.

¿Qué es el método HTTP QUERY?

QUERY es un método HTTP que pide al recurso de destino que ejecute la consulta descrita en el contenido de la solicitud y devuelva el resultado. El cuerpo de la solicitud y su Content-Type definen la consulta. El método es seguro (el cliente no espera ningún cambio de estado) e idempotente (repetirlo tiene el mismo efecto), así que clientes, proxies y cachés pueden reintentarlo y almacenarlo en caché como GET.

La especificación es RFC 10008, «El método HTTP QUERY», un Estándar Propuesto publicado en junio de 2026 por Julian Reschke (greenbytes), James M. Snell (Cloudflare) y Mike Bishop (Akamai). IANA lo ha añadido al Registro de métodos HTTP con «seguro: sí, idempotente: sí», justo al lado del método SEARCH de la era WebDAV en el que casi se convirtió.

Una solicitud QUERY se ve así:

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

select=surname,givenname,email&limit=10&match=%22email=*@example.*%22

El servidor responde con 200 OK y el resultado en el cuerpo.

Por qué GET y POST no eran suficientes

Tienes dos opciones para una lectura compleja antes de QUERY, y ambas presentan fugas.

GET pone todo en la URL. El RFC 10008 enumera cuatro problemas con eso:

Los límites de tamaño se desconocen de antemano, porque una solicitud atraviesa muchos sistemas. El RFC 9110 solo recomienda que los emisores y receptores admitan al menos 8000 octetos.
Codificar datos estructurados en una URI válida es un desperdicio.
Las URI se registran y se guardan en marcadores mucho más a menudo que los cuerpos de las solicitudes, lo que es un problema de privacidad para filtros sensibles.
Cada combinación de entradas de consulta se convierte en su propio recurso.

GET con cuerpo tampoco es la respuesta. El RFC 9110 dice que el contenido en una solicitud GET no tiene semántica definida. Algunos servidores lo leen, algunos lo descartan y algunos proxies rechazan la solicitud. No puedes contar con ello en toda la ruta.

POST funciona, pero miente sobre la intención. Una búsqueda POST se ejecuta bien, pero nada indica a un cliente, caché, proxy o biblioteca de reintentos que la operación es de solo lectura. Así que las cachés la omiten y los clientes no la reintentan tras una conexión interrumpida. Si has tenido que añadir a la fuerza una clave de idempotencia a una lectura pura solo para que los reintentos sean seguros, has sentido esto.

QUERY conserva el cuerpo de POST y añade las garantías de GET.

QUERY vs GET vs POST

Aquí está la comparación, basada en la Tabla 1 del RFC 10008:

Propiedad	GET	QUERY	POST
Seguro	Sí	Sí	Potencialmente no
Idempotente	Sí	Sí	Potencialmente no
Cuerpo de la solicitud	Sin semántica definida	Esperado, define la consulta	Esperado
URI para la consulta en sí	Sí, por definición	Opcional, mediante `Location`	No
URI para el resultado	Opcional, mediante `Content-Location`	Opcional, mediante `Content-Location`	Opcional, mediante `Content-Location`
Almacenable en caché	Sí	Sí, el cuerpo es parte de la clave de caché	Solo para GET o HEAD posteriores
Preflight CORS desde navegadores	No para solicitudes simples	Siempre	No para solicitudes simples

La versión corta: usa GET cuando la consulta quepa cómodamente en la URL, QUERY cuando no, y POST solo cuando la solicitud cambie el estado. Para repasar los métodos clásicos, consulta nuestras guías sobre métodos HTTP y GET vs POST.

Qué define el RFC 10008

Content-Type es obligatorio

Los servidores DEBEN rechazar una QUERY cuyo Content-Type falte o sea incoherente con el cuerpo. El RFC recomienda estos códigos de estado:

400 Bad Request: no hay tipo de medio, o un tipo que no coincide con el contenido. Los servidores no pueden inspeccionar el cuerpo para anularlo.
415 Unsupported Media Type: el recurso no admite ese formato de consulta.
422 Unprocessable Content: el formato es correcto, pero la consulta no puede ejecutarse, como un SQL que nombra una tabla que no existe.
406 Not Acceptable: el cliente pidió un tipo de respuesta que el recurso no puede producir.

Location y Content-Location

Un servidor puede devolver dos encabezados opcionales que convierten una QUERY en algo que puedes obtener con GET más tarde:

Content-Location apunta al resultado almacenado de esta ejecución específica. Puede ser temporal.
Location apunta a la consulta almacenada en sí. Un GET sobre ella vuelve a ejecutar la consulta con datos actualizados, sin reenviar el cuerpo.

El RFC sugiere que los clientes cambien a GET sobre la URI de Location para solicitudes repetidas, ya que el almacenamiento en caché de GET es más simple. Si devuelves cualquiera de los encabezados para una consulta con datos sensibles, la URI NO DEBERÍA contener partes sensibles del cuerpo original.

Almacenamiento en caché

Las respuestas a QUERY se pueden almacenar en caché. La clave de caché DEBE incluir el contenido de la solicitud y los metadatos relacionados, como el tipo de medio. Las cachés PUEDEN normalizar primero el cuerpo, por ejemplo eliminando la codificación de contenido o normalizando JSON para un tipo +json, para obtener más aciertos. La especificación advierte que una mala normalización puede devolver la respuesta incorrecta, así que espera que las CDN sean cuidadosas aquí.

Redirecciones

Un 301, 302, 307 o 308 significa «envía la misma QUERY a la nueva URI». A diferencia de POST, una QUERY no debe reescribirse a GET en un 301 o 302. Un 303 See Other significa «obtén el resultado con un GET en esta URI».

El encabezado Accept-Query

Accept-Query es un nuevo encabezado de respuesta que anuncia compatibilidad con QUERY y los formatos de consulta que acepta un recurso. Es una lista de Campo estructurado, así que analízala como tal:

Accept-Query: "application/jsonpath", application/sql;charset="UTF-8"

Los clientes también pueden descubrir la compatibilidad con OPTIONS y leer el encabezado Allow, o simplemente enviar la QUERY y manejar un 405 Method Not Allowed.

¿Qué herramientas admiten QUERY hoy?

La compatibilidad es desigual, así que prueba tu propio stack. Esto es lo que confirmamos el 28 de octubre de 2026:

Herramienta	Resultado
Servidor `http` de Node.js 24	`http.METHODS` incluye `QUERY`; un servidor simple recibió el método y el cuerpo
`fetch` de Node.js 24	Envió una QUERY con un cuerpo JSON
curl 8.7	`curl -X QUERY` con `-d` envió el método y el cuerpo
`http.client` de Python 3.14	Envió una QUERY con un cuerpo
OpenAPI 3.2	El objeto Path Item tiene un campo `query` para operaciones QUERY
Apidog CLI 2.2.12	El esquema `endpoint-create` acepta `"method": "query"`

Esta es la llamada curl que usamos contra un servidor Node local:

curl -i -X QUERY http://localhost:3000/products \
  -H "Content-Type: application/json" \
  -d '{"q":"running shoe","limit":2}'

El Fetch Standard solo prohíbe un cuerpo en GET y HEAD, así que los navegadores pueden enviar QUERY con un cuerpo. Sin embargo, QUERY no es un método de la lista segura de CORS, por lo que cada QUERY de origen cruzado activa un preflight. Tu servidor debe incluir QUERY en Access-Control-Allow-Methods.

Los vacíos están en medio de la red: proxies inversos, API gateways, WAF y CDN que incluyen métodos en listas de permitidos o que no usan el cuerpo como clave de su caché. Revisa cada salto antes de publicar. El boletín APIs You Won’t Hate señala que muchos frameworks web ya manejan QUERY directamente o mediante enrutamiento de métodos personalizados.

Cómo adoptar QUERY sin romper clientes

No tienes que eliminar tus endpoints de búsqueda POST.

Añade QUERY junto a la ruta POST. Apunta ambas al mismo handler. Los clientes nuevos usan QUERY; los antiguos siguen funcionando.
Anúncialo. Devuelve Accept-Query en el recurso e incluye QUERY en Allow en las respuestas OPTIONS y 405.
Haz cumplir Content-Type. Devuelve 400 o 415 como recomienda el RFC, y 422 para consultas que se analizan pero no pueden ejecutarse.
Usa 405 o 501 como respaldo. Los clientes deberían reintentar el mismo cuerpo como POST cuando un salto rechace QUERY.
Corrige CORS. Añade QUERY a Access-Control-Allow-Methods para clientes de navegador.
Decide sobre el almacenamiento en caché. Habilita el almacenamiento en caché compartido solo donde tu caché use el cuerpo como clave. De lo contrario, devuelve una URI de Location y deja que los clientes la obtengan con GET.
Documentalo. En OpenAPI 3.2, define la operación bajo query: en el path item:

openapi: 3.2.0
paths:
  /products:
    query:
      summary: Search products
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProductQuery'
      responses:
        '200':
          description: Matching products

Los filtros cortos y simples pueden seguir como cadenas de consulta en GET. El propio RFC 10008 dice que si tu consulta es así de corta, GET probablemente sea la mejor opción.

Deja que tu agente de programación pruebe un endpoint QUERY con Apidog CLI

Un método nuevo significa comprobar el camino feliz, cada código de error y la ruta de respaldo. Pásaselo a Claude Code, Codex o Cursor y deja que maneje el Apidog CLI.

Instala la CLI, inicia sesión y añade la skill de Apidog a tu agente:

npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com   # pick your agent when prompted

Luego dale a tu agente un prompt:

In Apidog project <projectId>, add a QUERY /products endpoint that takes a
JSON body {q, limit}. Create test cases that assert 200 with an array for a
valid body, 415 for Content-Type text/plain, and 400 with no Content-Type.
Run them against the staging environment and summarize any failures.

El agente lee cada esquema, valida su payload y solo entonces escribe:

apidog cli-schema get endpoint-create
apidog cli-schema validate endpoint-create --file endpoint.json
apidog endpoint create --project <projectId> --file endpoint.json
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project <projectId> --file case.json
apidog run --test-case <caseId> --project <projectId> -e <envId> -r cli,json

El endpoint.json que escribe establece "method": "query", que el esquema endpoint-create de la CLI enumera junto con get, post y los métodos WebDAV. Añade --upload-report para ver la ejecución en la aplicación Apidog. El mismo comando apidog run con -r junit se integra en CI; consulta cómo ejecutar pruebas de API en CI con apidog run y cómo usar la CLI de Apidog en Claude Code. El plan Gratuito de Apidog cubre hasta 4 usuarios.

Preguntas frecuentes

¿El método HTTP QUERY es un estándar oficial? Sí. El RFC 10008 es un RFC de Standards Track, Proposed Standard, publicado en junio de 2026, e IANA enumera QUERY en el HTTP Method Registry como seguro e idempotente.

¿QUERY es solo GET con un cuerpo? Casi, pero está mejor definido. El RFC 9110 no da semántica a un cuerpo GET, por lo que los intermediarios pueden ignorarlo o rechazarlo. QUERY convierte el cuerpo en la consulta, requiere un Content-Type e incorpora el cuerpo a la clave de caché.

¿Cuándo debería usar QUERY en lugar de POST? Usa QUERY para cualquier búsqueda o filtro de solo lectura que sea demasiado grande o demasiado sensible para una URL. Mantén POST para solicitudes que crean o cambian algo.

¿Pueden los navegadores enviar solicitudes QUERY? Sí, mediante fetch con un método personalizado. Las solicitudes QUERY de origen cruzado siempre necesitan un preflight CORS, así que tu servidor debe permitir el método.

¿Se almacenan en caché las respuestas a QUERY? Pueden estarlo. Las cachés deben incluir el cuerpo de la solicitud y sus metadatos en la clave de caché. Muchas CDN y proxies aún no lo hacen, así que revisa la tuya o devuelve una URI de Location que los clientes puedan obtener con GET.

¿OpenAPI admite QUERY? OpenAPI 3.2 añade un campo query al objeto Path Item para operaciones QUERY, así que puedes documentarlas sin extensiones.