Conoce QUERY: el nuevo método HTTP que resuelve un problema de toda la vida

Si has construido APIs, ya conoces la rutina: GET para leer datos, POST para crearlos, PUT/DELETE para actualizarlos y eliminarlos. Estos cuatro verbos han sido la base de HTTP durante décadas. Ahora viene un quinto, llamado QUERY, y resuelve un problema que los desarrolladores llevan años sorteando.

El problema: GET y POST no terminan de encajar

Imagina que estás construyendo una API de búsqueda de productos. Quieres filtrar por categoría, rango de precio, valoración y orden. Hoy tienes dos opciones, y ninguna es perfecta.

Opción 1: usar GET. Es simple y el navegador lo cachea automáticamente. Pero todo tiene que ir en la URL:

GET /api/products/search?category=electronics&minPrice=100&maxPrice=500&rating=4&sortBy=rating

Esto se complica rápido. Las URLs tienen un límite de longitud. Cada valor llega como cadena de texto, así que un booleano como true o un número como 4 requieren conversión manual en el servidor. Los filtros anidados (como "electrónica o libros, pero no juguetes") son un dolor de cabeza para codificar. Y toda la URL, filtros incluidos, termina en los logs de tu servidor.

Opción 2: usar POST. Puedes enviar un JSON limpio en el cuerpo:

{
  "categories": ["electronics"],
  "price": { "min": 100, "max": 500 },
  "minRating": 4,
  "sortBy": "rating"
}

Sin dolores de cabeza de codificación. Pero POST significa "estoy creando o cambiando algo" para cualquier navegador o CDN. Aunque tu búsqueda no modifique nada, el navegador nunca va a cachear la respuesta, y no puedes guardar la petición como favorito. Por esto GraphQL —un lenguaje construido enteramente alrededor de consultas— envía todas sus peticiones por POST. Necesita un cuerpo para la consulta, pero a cambio pierde todo el cacheo.

La solución: QUERY

QUERY es un nuevo método HTTP diseñado para combinar lo mejor de ambos:

• Como GET, es seguro e idempotente: nunca modifica nada en el servidor, y llamarlo varias veces te da siempre el mismo resultado. Esto es lo que lo hace cacheable.
• Como POST, permite enviar un cuerpo en la petición, así que obtienes un JSON limpio y estructurado sin tener que meterlo todo en una URL.

Aquí tienes la misma búsqueda, ahora con QUERY:

const response = await fetch('/api/products/search', {
  method: 'QUERY',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    categories: ['electronics'],
    price: { min: 100, max: 500 },
    minRating: 4,
    sortBy: 'rating',
  }),
});
 
const data = await response.json();
console.log(data);

Cómo se ve en el servidor

Node.js y Express (desde la versión 5) ya soportan QUERY. Aquí tienes un ejemplo mínimo con los tres métodos lado a lado:

import express from 'express';
const app = express();
app.use(express.json());
 
// La forma clásica: todo en la URL
app.get('/api/products/search', (req, res) => {
  const { category, minPrice, maxPrice, rating, sortBy } = req.query;
  res.json(searchProducts({ category, minPrice, maxPrice, rating, sortBy }));
});
 
// El truco habitual: un cuerpo, pero nunca cacheado
app.post('/api/products/search', (req, res) => {
  res.json(searchProducts(req.body));
});
 
// La nueva forma: cuerpo Y cacheable
app.query('/api/products/search', (req, res) => {
  res.json(searchProducts(req.body));
});
 
app.listen(3000);

¿Por qué no simplemente añadir un cuerpo a GET?

Buena pregunta, y la respuesta es básicamente "porque rompería internet". Nada en la especificación de HTTP prohíbe explícitamente enviar un cuerpo con GET, pero la especificación dice que no deberías hacerlo, y cada navegador, proxy y servidor ha construido su propio comportamiento basándose en esa suposición. Algunas herramientas ignoran el cuerpo de un GET, otras lo rechazan, otras lo dejan pasar. Cambiar ese comportamiento de golpe en todos lados sería un caos. Introducir un método completamente nuevo con reglas claras es mucho más seguro.

Cuándo usar cada uno

flowchart TD
    A[Necesitas obtener datos de una API] --> B{¿Necesitas enviar datos<br/>complejos, anidados o no textuales?}
    B -- No --> C[Usa GET]
    B -- Sí --> D{¿La respuesta debería ser<br/>cacheable o guardable como favorito?}
    D -- Sí --> E[Usa QUERY]
    D -- No, y modifica datos --> F[Usa POST]

Qué significa esto ahora mismo

QUERY todavía está en camino de convertirse en un estándar web completo, y los navegadores todavía no han implementado el cacheo nativo para él. Eso llegará más adelante, igual que ocurrió con GET en su momento. El soporte ya existe en Node.js y Express, y se espera que más frameworks lo adopten a medida que el estándar madure.

Si quieres probarlo en producción hoy, hazlo con cuidado: mantén tu endpoint GET o POST existente funcionando tal cual, y añade QUERY como un endpoint adicional y opcional. Así, los clientes que entiendan QUERY podrán usarlo, y el resto seguirá funcionando exactamente igual que antes.

Para cerrar

QUERY llena un vacío real en HTTP: una forma de hacer lecturas seguras, cacheables e idempotentes mientras sigues enviando un cuerpo completo en la petición. No va a reemplazar a GET ni a POST: se sitúa entre ambos, pensado específicamente para consultas de lectura complejas. Vale la pena seguir de cerca el soporte de frameworks y navegadores en los próximos años; es una de esas raras incorporaciones a un protocolo central de internet que merece la pena entender desde ya.