Durante años muchas APIs han ocultado búsquedas complejas detrás de un POST. No porque tuviera sentido semántico, sino porque era la salida práctica. Un GET funciona 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 razonable donde meterlo todo. El resultado fue un patrón que cualquier equipo de backend reconoce: 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. El 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 gestionan endpoints de búsqueda avanzada, QUERY marca una dirección 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. El 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.
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. A cambio se perdía semántica. Para un proxy, una CDN, un cliente HTTP o un sistema de reintentos, POST no comunica que una petición 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:
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
}
Antes esto solía acabar en:
POST /api/servidores/search HTTP/1.1 Content-Type: application/json
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:
Accept-Query: application/json, application/jsonpath, application/sql
Esto permite descubrir capacidades sin depender solo de documentación externa. Un cliente puede 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 es semántica. Un endpoint de búsqueda avanzada deja de camuflarse como POST. Ayuda al diseño de APIs, a los SDKs, a la documentación y a los equipos que operan infraestructura.
La segunda 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. La RFC da una señal mucho más limpia a la cadena HTTP.
La tercera es la caché. QUERY está definido como cacheable, lo que 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 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 |
Una posibilidad interesante es que el servidor responda 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. Viene bien 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é. 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», 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 |
Poner filtros en el body no los convierte en secretos. Reduce exposición accidental en URLs y logs intermedios, pero el body sigue pudiendo registrarse en aplicación o trazas. TLS, políticas de logging y validación siguen siendo obligatorios.
Cuándo usar GET, QUERY o POST
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: 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 | POST |
Actualizar un recurso completo | PUT |
Modificar parte de un recurso | PATCH |
Una guía mínima para empezar
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.
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-Type
La parte delicada es 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 sirven resultados incorrectos. Para búsquedas con permisos por usuario habrá que usar caché privada, variar por identidad o directamente no cachear.
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 del stack. Antes hay que validar soporte en servidor, proxy, CDN, WAF, clientes HTTP, observabilidad y CORS. Para muchos entornos es 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.
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 Nginx, Envoy, frameworks backend y clientes HTTP traten QUERY como ciudadano de primera, el patrón podrá entrar en arquitecturas reales.
HTTP no cambia todos los días. Cuando cambia para corregir una práctica que millones de APIs habían normalizado, conviene prestar atención.
Imagen: Pexels / Miguel Á. Padriñán