Durante años, muchas APIs han escondido búsquedas complejas detrás de un POST. No porque tuviera sentido semántico, sino porque era la salida práctica. Un GET funciona muy bien para lecturas simples, pero cuando una búsqueda necesita filtros anidados, arrays, rangos, ordenaciones múltiples o estructuras JSON, la URL deja de ser un sitio cómodo para meterlo todo. El resultado fue un patrón conocido por cualquier equipo de backend: endpoints de lectura con cuerpo de POST.
HTTP acaba de cubrir ese hueco con RFC 10008, que define el método QUERY como estándar propuesto de IETF. Su objetivo es claro: permitir una petición de consulta con body, como POST, pero manteniendo las propiedades que se esperan de una lectura: es segura, idempotente y cacheable.
No significa que mañana todos los frameworks, proxies, balanceadores, CDNs y WAFs lo soporten sin tocar nada. La adopción llevará tiempo. Pero para quienes diseñan APIs, mantienen infraestructura web o pelean con endpoints de búsqueda avanzada, QUERY marca una dirección bastante lógica: dejar de usar POST como contenedor genérico para lecturas complejas.
El problema real: GET se queda corto y POST miente un poco
GET es el método natural para pedir datos. Es seguro, idempotente y cacheable. Su problema aparece cuando la consulta deja de ser sencilla. Una URL puede llevar parámetros, pero no está pensada para transportar estructuras grandes o muy expresivas. Además, los límites reales no dependen solo del servidor. La petición puede pasar por navegadores, proxies, balanceadores, gateways, firewalls, CDNs y sistemas de observabilidad, cada uno con sus propias restricciones.
También hay otro detalle menos visible: la URL se registra en logs con mucha más facilidad que el cuerpo de una petición. Si se envían filtros sensibles en query string, pueden acabar en historiales, métricas, trazas, cabeceras de referencia o registros intermedios.
POST resolvía la parte física del problema porque acepta body. Se podía mandar un JSON limpio, con filtros bien estructurados, sin pelearse con encoding de URL. Pero a cambio se perdía semántica. Para un proxy, una CDN, un cliente HTTP o un sistema de reintentos, POST no comunica de forma nativa “esto es una lectura segura”. Puede ser una búsqueda, pero también puede crear un pedido, lanzar una tarea, enviar un formulario o modificar estado.
| Método | Seguro | Idempotente | Body | Cacheable | Uso natural |
|---|---|---|---|---|---|
| GET | Sí | Sí | Sin semántica definida | Sí | Lecturas simples |
| QUERY | Sí | Sí | Sí | Sí | Consultas complejas |
| POST | No necesariamente | No necesariamente | Sí | Condicional | Creación, acciones o procesos con efectos |
En HTTP, “seguro” no significa cifrado, autenticado ni protegido frente a ataques. Significa que el cliente no pide cambiar el estado del recurso. Un GET o un QUERY pueden quedar registrados, consumir CPU o actualizar métricas, pero no deberían crear, modificar ni borrar datos como parte de su operación principal.
Qué aporta QUERY
QUERY permite enviar el contenido de la consulta en el body de la petición. Ese contenido puede ser JSON, SQL, JSONPath, formularios u otro tipo de medio que el servidor declare soportado. La semántica no la define solo el método, sino también el recurso y el Content-Type.
Un ejemplo simple podría ser:
QUERY /api/servidores/search HTTP/1.1
Host: ejemplo.com
Content-Type: application/json
Accept: application/json
{
"where": {
"region": ["mad1", "ams1"],
"status": "active",
"ram_gb": { "gte": 128 },
"tags": ["proxmox", "production"]
},
"sort": [
{ "field": "created_at", "direction": "desc" }
],
"limit": 50
}Lenguaje del código: JavaScript (javascript)Esto antes solía acabar en algo como:
POST /api/servidores/search HTTP/1.1
Content-Type: application/jsonLenguaje del código: HTTP (http)Funcionaba, pero el método no decía la verdad completa. QUERY sí la dice: el servidor va a procesar una consulta incluida en el body y devolver el resultado, sin que el cliente espere cambios de estado.
La RFC introduce también la cabecera Accept-Query, con la que un recurso puede indicar qué formatos acepta para consultas. Por ejemplo:
Accept-Query: application/json, application/jsonpath, application/sqlLenguaje del código: HTTP (http)Esto permite descubrir capacidades sin depender solo de documentación externa. Un cliente podría preguntar primero con HEAD u OPTIONS, leer Accept-Query y decidir si manda un JSON, un formulario o una consulta en otro formato.
Ventajas para APIs, CDNs y reintentos
La primera ventaja es semántica. Un endpoint de búsqueda avanzada deja de camuflarse como POST. Esto ayuda al diseño de APIs, a los SDKs, a la documentación y a los equipos que operan infraestructura. La intención queda más clara desde el método HTTP.
La segunda ventaja es la idempotencia. Si una conexión cae a mitad de una petición QUERY, un cliente o intermediario puede repetirla sin miedo a duplicar una compra, crear dos registros o lanzar dos trabajos. Eso no elimina la necesidad de diseñar bien el backend, pero da una señal mucho más limpia a la cadena HTTP.
La tercera es la caché. QUERY está definido como cacheable. Eso abre una puerta importante para búsquedas pesadas que hoy se ejecutan una y otra vez porque llegaron como POST. La RFC exige que la clave de caché incorpore el contenido de la petición y metadatos relacionados. Es más complejo que cachear GET, pero por fin queda definido dentro del protocolo.
| Ventaja | Impacto práctico |
| Body estructurado | Filtros complejos sin forzar la URL |
| Semántica de lectura | Mejor diseño de APIs y contratos |
| Idempotencia | Reintentos más seguros tras fallos |
| Caché HTTP | Posible reutilización en proxies y CDNs |
| Menos exposición en URL | Menos datos sensibles en logs de URI |
| Descubrimiento con Accept-Query | El servidor puede anunciar formatos aceptados |
| Content-Location y Location | Posibilidad de convertir resultados o consultas en recursos GET |
Una posibilidad interesante es que el servidor responda a una consulta QUERY con Location o Content-Location. Así puede asignar una URI a la consulta guardada o al resultado, y el cliente puede usar GET después. Es útil para informes pesados, búsquedas recurrentes o consultas que conviene materializar.
Desventajas y problemas de adopción
QUERY no es magia. El primer problema es el soporte real. Muchos servidores, proxies, CDNs, WAFs, librerías, middlewares y herramientas de monitorización están acostumbrados a GET, POST, PUT, PATCH y DELETE. Un método nuevo puede acabar bloqueado, no registrado correctamente, mal clasificado en métricas o tratado como tráfico sospechoso.
El segundo problema está en la caché. Sí, QUERY es cacheable, pero cachearlo bien exige que la infraestructura entienda el body. No basta con mirar la URL. Dos cuerpos JSON con el mismo significado, pero distinto orden de claves o espacios, podrían generar claves diferentes si no se normalizan. La RFC contempla esta complejidad, pero llevarlo a producción exigirá soporte serio por parte de CDNs y proxies.
El tercer punto está en CORS. En navegador, QUERY no entra dentro de los métodos “simples” de CORS, que se limitan a GET, HEAD y POST. En llamadas cross-origin habrá preflight con OPTIONS, y las APIs tendrán que responder con Access-Control-Allow-Methods: QUERY cuando corresponda.
| Riesgo o limitación | Qué revisar |
| Soporte de servidores | Nginx, Apache, Envoy, HAProxy, Node, Go, Java, .NET |
| CDNs y proxies | Caching por body, claves, normalización y purga |
| WAFs | Reglas que bloqueen métodos desconocidos |
| Observabilidad | Logs, métricas, trazas y dashboards |
| CORS | Preflight y Access-Control-Allow-Methods |
| SDKs | Clientes generados desde OpenAPI u otras herramientas |
| Backward compatibility | Fallback temporal a POST |
| Seguridad | Límites de tamaño, validación y control de coste |
También hay que recordar algo básico: poner filtros en el body no los convierte en secretos. Es mejor que exponerlos en la URL para ciertos casos, pero siguen viajando al servidor y pueden acabar en logs de aplicación, trazas, APM o dumps si no se controla bien. TLS, políticas de logging y minimización de datos siguen siendo obligatorios.
Cuándo usar GET, QUERY o POST
La regla práctica puede ser bastante sencilla. GET sigue siendo la mejor opción para lecturas simples, estables y fáciles de representar en una URL. Si una búsqueda cabe de forma natural en query string, no hace falta complicarla.
QUERY encaja cuando la operación es una lectura, pero la entrada necesita estructura. Es el caso de buscadores avanzados, filtros de inventario, analítica, reportes, consultas sobre logs, búsquedas vectoriales, GraphQL de solo lectura o endpoints de reporting con muchos parámetros.
POST debe quedarse para lo que realmente implica acción: crear recursos, enviar formularios, lanzar procesos, ejecutar comandos, cambiar estado, iniciar flujos o realizar operaciones que no son seguras. También puede seguir siendo el fallback durante años mientras el ecosistema adopta QUERY.
| Caso | Mejor método |
/users?status=active&page=2 | GET |
| Buscar servidores por tags, región, RAM y fecha | QUERY |
| Consulta analítica con filtros anidados | QUERY |
| GraphQL query de solo lectura | QUERY, cuando haya soporte |
| Crear usuario | POST |
| Lanzar backup bajo demanda | POST |
| Generar informe que modifica estado o consume cupo no repetible | POST |
| Actualizar un recurso completo | PUT |
| Modificar parte de un recurso | PATCH |
Para administradores de sistemas, la recomendación inicial no es abrir QUERY en producción sin más. Lo razonable es probar primero en entornos controlados: API interna, staging, gateway específico o endpoints nuevos donde se pueda medir cómo se comportan proxy, WAF, caché, APM y clientes.
Una guía mínima para empezar
Un diseño prudente podría seguir estos pasos:
| Paso | Recomendación |
| 1 | Identificar endpoints POST que en realidad son lecturas |
| 2 | Separar operaciones seguras de acciones con efectos |
| 3 | Definir Content-Type estricto, por ejemplo application/json |
| 4 | Publicar Accept-Query en los recursos que lo soporten |
| 5 | Aplicar límites de tamaño y complejidad del body |
| 6 | Normalizar consultas si se van a cachear |
| 7 | Configurar CORS, WAF, logs y métricas |
| 8 | Mantener fallback POST mientras los clientes migran |
Un ejemplo de respuesta bien planteada podría incluir cabeceras de caché y descubrimiento:
HTTP/1.1 200 OK
Content-Type: application/json
Accept-Query: application/json
Cache-Control: public, max-age=60
Content-Location: /api/servidores/search-results/8f7a21
Vary: Accept, Content-TypeLenguaje del código: HTTP (http)La parte delicada será la clave de caché. Si se cachea QUERY en una CDN, la clave debe tener en cuenta el body, el Content-Type y cualquier cabecera que cambie la respuesta. De lo contrario, se corre el riesgo de servir resultados incorrectos. Para búsquedas con permisos por usuario, además, habrá que usar caché privada, variar por identidad o directamente no cachear.
El cambio será lento, pero necesario
QUERY no va a reemplazar a GET ni a POST. Los ordena. GET seguirá siendo perfecto para lecturas simples y URLs compartibles. POST seguirá siendo el método natural para acciones y creación de recursos. QUERY ocupa el espacio que llevaba años vacío: consultas seguras con body.
Su adopción dependerá menos de la RFC y más de la infraestructura. Cuando Cloudflare, AWS, Fastly, Nginx, Envoy, HAProxy, frameworks backend, clientes HTTP y herramientas de OpenAPI empiecen a tratar QUERY como ciudadano de primera, el patrón podrá entrar en arquitecturas reales. Hasta entonces, habrá que convivir con POST para lecturas complejas y diseñar migraciones con calma.
La novedad importa porque HTTP no cambia todos los días. Y cuando cambia para corregir una práctica que millones de APIs habían normalizado, conviene prestar atención.
Durante años, meter filtros complejos en un POST fue una solución práctica. Ahora empieza a ser una deuda semántica con fecha de salida.
Preguntas frecuentes
¿QUERY sustituye a GET?
No. GET sigue siendo la mejor opción para lecturas simples, cacheables y representables en una URL. QUERY está pensado para consultas de lectura que necesitan body.
¿QUERY sustituye a POST?
Tampoco. POST sigue siendo el método adecuado para crear recursos, lanzar acciones o ejecutar operaciones con efectos. QUERY sirve para consultas seguras e idempotentes.
¿Puedo usar QUERY ya en producción?
Depende de tu stack. Antes hay que validar soporte en servidor, proxy, CDN, WAF, clientes HTTP, observabilidad y CORS. Para muchos entornos será mejor empezar con pilotos internos.
¿QUERY es más seguro porque no mete filtros en la URL?
No en sentido de seguridad informática. Reduce exposición accidental en URLs y logs intermedios, pero el body sigue pudiendo registrarse en aplicación o trazas. TLS, control de logs y validación siguen siendo necesarios.
