Skip to main content

¿Qué es?

QUERY es un método HTTP estandarizado en la RFC 10008: es como un GET, pero lleva cuerpo. Es seguro (solo lectura) e idempotente, así que se comporta igual que un GET — la única diferencia es que los filtros viajan en el cuerpo JSON en lugar de la query string. Por ahora lo soportan solo los endpoints de listado que aparecen en la tabla de abajo; el resto de la API sigue aceptando únicamente GET. Y el GET de esos endpoints sigue funcionando exactamente igual: QUERY es una alternativa opcional, no un reemplazo.

¿Por qué usarlo?

Cuando filtras por un identificador del cliente —una cédula, un teléfono, un email o una llave Bre‑B— con GET ese dato queda en la URL (?search=1234567890), y las URLs terminan guardadas en logs de acceso, historiales y proxies intermedios. Con QUERY ese mismo filtro va en el cuerpo, fuera de la URL:
  • Privacidad: los identificadores sensibles quedan fuera de la URL, y por tanto fuera de los access logs y del historial del navegador.
  • Sin límite de tamaño: filtros grandes o anidados no chocan con el límite de longitud de la URL.
  • Semántica correcta: al ser seguro e idempotente, clientes y proxies pueden reintentarlo sin riesgo de efectos secundarios.

Endpoints que lo soportan

Cómo se usa

Toma los mismos parámetros que enviarías en la query string (filter[...], sort, page) y mándalos como JSON en el cuerpo, con el header Content-Type: application/json:
La respuesta es idéntica a la del GET: el mismo formato paginado (data, current_page, total, …).
Si un mismo filtro va tanto en la query string como en el cuerpo, gana el de la query string.

Compatibilidad de clientes

QUERY funciona con cualquier cliente HTTP que permita métodos personalizados: fetch, axios, requests de Python, curl, Guzzle, entre otros. Algunas librerías muy antiguas no lo soportan; en ese caso, sigue usando GET, que nunca dejará de funcionar.