Todo lo que hemos diseñado hasta ahora funciona igual de bien con 5 cafés que con 5.000… hasta que llega el primer GET /v1/cafes sobre un catálogo real y la respuesta pesa 40 MB. Las colecciones son el punto donde una API bien diseñada se distingue de una que aguanta solo en el entorno de desarrollo. Esta lección diseña las colecciones grandes de Tienda Aroma: cómo se filtran, cómo se ordenan, cómo se parten en páginas —con los tres modelos existentes y sus consecuencias reales— y cómo se busca texto. Es diseño de contrato, no de implementación: aquí se decide qué parámetros existen y qué prometen, y el módulo 3 los implementará tal cual.

1. Por qué una colección sin límites es un problema
2. Filtrado: convenios de query params
3. Filtros por rango y por múltiples valores
4. Por qué no inventar un lenguaje de consulta en la URL
5. Ordenación
6. Paginación por offset
7. Paginación por página
8. Paginación por cursor
9. Comparativa y deep paging
10. Dónde viajan los metadatos de paginación
11. Búsqueda de texto
12. Valores por defecto, límites y documentación

GET /v1/cafes sin restricciones parece inofensivo. Con 137 cafés lo es. Con 50.000 referencias, o con GET /v1/pedidos sobre el histórico completo, deja de serlo por cuatro motivos simultáneos:

El último punto es el importante y el que suele pasarse por alto: una colección sin límite máximo es un vector de ataque, y no hace falta mala intención —basta un script de un socio con un bucle mal escrito—. Por eso la primera decisión no es "cómo pagino", sino "la paginación es obligatoria y el servidor la impone aunque el cliente no la pida".

Como fijamos en 02-02, los criterios de selección van en la query string. El convenio base de Tienda Aroma es el más simple posible: un parámetro por campo, igualdad exacta.

Reglas del contrato:

• El nombre del parámetro es el nombre del campo en la representación (origen, tueste, estado, clienteId). Previsibilidad: quien ha visto el JSON ya sabe filtrar.
• Varios filtros se combinan con Y lógico. Nunca con O; para eso está el multivalor de la sección 3.
• Un filtro desconocido devuelve 400 con parametro_invalido. Ignorarlo en silencio es peor: el cliente cree que ha filtrado y recibe todo el catálogo.
• Un valor inválido devuelve 400: ?tueste=tostadísimo no es un enumerado válido.
• Sin resultados es 200 con {"datos": [], "total": 0}, nunca 404 (02-03).
• Los valores se codifican en la URL: ?origen=Etiop%C3%ADa.

Filtros publicados en la v1 de Tienda Aroma:

La lista de filtros es cerrada y forma parte del contrato. No se filtra por cualquier campo "porque el ORM lo permite": cada filtro publicado hay que documentarlo, validarlo, probarlo, indexarlo y mantenerlo para siempre.

El convenio de Tienda Aroma son dos parámetros con sufijo, ambos inclusivos:

Convención de sufijos: Min/Max para números, Desde/Hasta para fechas. Los dos extremos son opcionales e independientes: ?precioMin=10 significa "de 10 € en adelante".

Alternativas que existen y que Tienda Aroma no usa, para que las reconozcas:

Para "esto o aquello" sobre el mismo campo, lista separada por comas:

La alternativa —repetir el parámetro, ?tueste=claro&tueste=medio— es igual de válida y la usan muchas APIs, pero su comportamiento depende del framework y de la biblioteca del cliente (algunos se quedan con el último valor). La coma es explícita y no admite interpretaciones. Limitación asumida: los valores no pueden contener comas; en Tienda Aroma solo se admite multivalor en enumerados e identificadores, donde eso no ocurre.

Resumiendo la semántica completa, que hay que documentar de forma explícita:

Antes o después alguien propondrá algo así:

Es tentador: resuelve cualquier consulta futura sin tocar la API. Y casi siempre es un error:

• Hay que escribir un parser y un evaluador, con sus errores de sintaxis, sus mensajes y sus casos límite. Es un proyecto, no un parámetro.
• Riesgo de inyección: pasar la expresión al motor de datos sin traducirla con cuidado es una vía directa a NoSQL injection o SQL injection (04-02).
• Imposible de acotar: el cliente puede construir consultas con coste arbitrario. Adiós a los índices y a las previsiones de capacidad.
• Imposible de documentar bien en OpenAPI: el parámetro es una cadena libre, así que no hay validación automática, ni autocompletado, ni mocks útiles (02-08).
• La caché sufre: infinitas combinaciones de URL, ninguna reutilizable.

Existen estándares serios para esto —OData y GraphQL (01-07)— y la lección es que, si de verdad necesitas consultas arbitrarias, adoptas uno de ellos con los ojos abiertos, no te inventas un dialecto. Tienda Aroma se queda con filtros explícitos: cubren los casos de uso reales, se documentan solos y son predecibles en coste. Si aparece una consulta legítima que no encaja, se añade un filtro nuevo (cambio retrocompatible, 02-07) o se crea un recurso específico.

Un solo parámetro, ordenar, con el nombre del campo y un guion delante para el orden descendente:

Detalles del contrato:

• Campos ordenables cerrados y documentados por colección. /cafes: nombre, precioEuros, stock, fechaCreacion, puntuacionMedia. Un campo no permitido devuelve 400 con parametro_invalido. La razón es de rendimiento: cada campo ordenable necesita su índice.
• Orden por defecto, también documentado: /cafes por nombre ascendente, /pedidos por -fechaCreacion, /resenas por -fechaCreacion.
• Orden múltiple con comas, de mayor a menor prioridad.

Un orden es estable cuando dos peticiones idénticas devuelven los elementos en el mismo orden. Suena obvio, pero no lo es si ordenas por un campo con valores repetidos: la base de datos puede devolver los empates en cualquier orden entre una consulta y la siguiente.

Consecuencia directa y muy real al paginar:

Si el motor resuelve los empates de forma distinta en cada consulta, hay cafés que aparecen en las dos páginas y cafés que no aparecen en ninguna. El usuario ve duplicados y pierde elementos, y el bug es intermitente e imposible de reproducir en desarrollo con 10 filas.

Solución, y es contrato: el servidor siempre añade un criterio de desempate único al final del orden solicitado, típicamente el id.

No aparece en la URL, pero se documenta: "el orden se desempata siempre por id ascendente". Sin esto, ninguna paginación es fiable.

El modelo más extendido: "salta N elementos y dame M".

A favor: es trivial de entender, permite saltar a cualquier página (desplazamiento = (pagina - 1) * limite) y da el total, con lo que el cliente puede pintar "137 resultados, página 3 de 7".

En contra, dos problemas serios que veremos en la sección 9: se degrada con desplazamientos grandes y no es estable frente a inserciones.

Es el mismo modelo con otra aritmética, más cómoda para quien pinta paginadores:

Ventaja: el cliente no calcula nada. Inconveniente: es exactamente igual de frágil que el offset, porque por debajo se traduce a un desplazamiento; solo cambia la forma de pedirlo. Y añade una ambigüedad clásica: ¿la primera página es la 1 o la 0? Cualquiera de las dos vale mientras esté documentada; equivocarse cuesta un bug de 20 elementos que nadie ve.

Decisión de Tienda Aroma: no se ofrecen pagina/porPagina. Un único mecanismo (limite/desplazamiento) es más consistente que dos equivalentes, y el cálculo de la página lo hace el cliente en una línea.

En lugar de "salta 5.000", el servidor entrega un puntero opaco a la posición en la que se quedó.

Cómo funciona por dentro: el cursor codifica (normalmente en Base64) los valores de la última fila entregada según el orden vigente —aquí, fechaCreacion e id—. La consulta siguiente no dice "salta 5.000 filas", dice "dame las filas posteriores a (2026-03-14, ped_5001)", que el índice resuelve al instante sea cual sea la profundidad.

Reglas de Tienda Aroma para los cursores:

• Son opacos. La documentación prohíbe expresamente descodificarlos o construirlos: su contenido puede cambiar sin previo aviso.
• Incluyen el orden. Un cursor obtenido con ?ordenar=-fechaCreacion no vale para ?ordenar=precioEuros: al mezclarlos, 400 con parametro_invalido.
• No hay total en las colecciones paginadas por cursor: calcularlo exige contar toda la tabla, que es justo el coste que queríamos evitar. Se documenta la ausencia.
• No se puede saltar a la página N: solo hay "siguiente" y "anterior". Es el precio del modelo.

Pedir la página 5.000 con offset obliga al motor a leer y descartar 100.000 filas antes de devolver 20:

El coste crece linealmente con el desplazamiento: la página 1 tarda milisegundos y la 5.000 puede tardar segundos y castigar a toda la base de datos. Con cursor, el coste es el mismo en la página 1 que en la 5.000.

Mitigación de Tienda Aroma: desplazamiento máximo de 10.000. Superarlo devuelve 400 con parametro_invalido y un mensaje que remite al mecanismo adecuado: "para recorrer la colección completa, usa la paginación por cursor".

El otro problema del offset, ilustrado con /pedidos ordenado por -fechaCreacion:

Con una inserción, se duplica un elemento; con un borrado, se omite uno, que es peor porque es invisible. En un catálogo que cambia poco, es tolerable; en una exportación contable, es inaceptable.

Decisión de Tienda Aroma:

Coexistir es legítimo siempre que cada colección documente cuál usa y los parámetros no se mezclen: enviar cursor y desplazamiento a la vez devuelve 400.

Tres sitios posibles, y no son excluyentes.

a) En el cuerpo, aprovechando el envoltorio decidido en 02-05:

b) En cabeceras propias, estilo GitHub:

c) En la cabecera Link (RFC 8288), el mecanismo estándar de la web:

Decisión de Tienda Aroma —coherente con lo fijado en el módulo 1—: total en el cuerpo y navegación en la cabecera Link.

Por qué esta combinación y no otra:

• Es exactamente la hipermedia selectiva de nivel 2 que decidimos en 01-05: enlaces donde aportan (navegación), sin convertir el cuerpo en un documento hipermedia.
• Link es un estándar con rel registrados, no una invención de la casa, y funciona igual para JSON, CSV o PDF.
• Los enlaces vienen construidos: el cliente no recalcula desplazamientos ni arrastra los filtros a mano. Fíjate en que cada enlace conserva todos los parámetros de la petición original —filtros, orden y campos—, que es justo el error que más se comete al implementarlo.
• total en el cuerpo porque es un dato del resultado, no de la navegación, y el cliente JavaScript lo tiene a mano sin parsear cabeceras.
• X-Total-Count no se usa: sería duplicar total con un nombre desaconsejado.

Con cursor, Link lleva solo next (y prev si el modelo lo permite), sin first ni last, y el cuerpo no lleva total. Y en la última página no hay rel="next": su ausencia es la señal de fin de colección, y así se documenta.

Filtrar es igualdad exacta; buscar es otra cosa: parcial, difusa, con relevancia. El parámetro reservado es q:

Contrato de q en Tienda Aroma:

• Busca en nombre, origen y notasCata, y así queda documentado (una búsqueda que no dice dónde busca es una caja negra).
• Insensible a mayúsculas y a acentos: q=etiopia encuentra "Etiopía".
• Se combina con los filtros con Y lógico.
• Mínimo 2 caracteres; con menos, 400 con parametro_invalido.
• El orden por defecto pasa a ser por relevancia cuando hay q, salvo que se indique ordenar explícitamente. Y ojo: ordenar por relevancia no es estable, así que se desempata por id igual que en la sección 5.

Cuando deja de ser "filtrar una colección" y se convierte en una funcionalidad con entidad propia:

Tienda Aroma no crea /busqueda en la v1: con ?q= sobre cada colección basta. Queda anotado como candidato para cuando exista el blog.

Hay un caso legítimo en el que la consulta no cabe en una URL: informes del panel interno con muchos criterios, listas largas de identificadores o expresiones que superan el límite práctico de longitud de una URL (unos 2.000 caracteres en la mayoría de servidores e intermediarios).

Es un compromiso consciente: se pierde la caché y POST deja de ser "crear" para significar "procesar esta consulta", y por eso el recurso se llama consultas (un sustantivo, 02-02) y devuelve 200, no 201. Tienda Aroma no lo incluye en la v1, pero deja escrito el patrón para cuando el panel lo necesite, en lugar de improvisarlo.

Aquí se cierra el contrato de colecciones, y esta tabla es la que el módulo 3 implementará literalmente:

Dos decisiones que conviene razonar:

• limite por encima del máximo devuelve 400, no se recorta en silencio. Recortar es tentador ("sé amable con el cliente"), pero deja al consumidor creyendo que ha recibido 1.000 elementos cuando solo tiene 100: paginará mal y perderá datos sin enterarse. Fallar de forma visible es más amable a medio plazo.
• El servidor pagina aunque el cliente no lo pida. GET /v1/cafes sin parámetros devuelve 20 elementos, total y la cabecera Link con next. No hay forma de pedir "todo".

Y así queda documentado cada parámetro en la referencia (02-08): nombre, tipo, obligatoriedad, valor por defecto, valores admitidos, comportamiento ante valores inválidos y un ejemplo ejecutable. En OpenAPI, esto se escribe una sola vez como parámetros reutilizables y se referencia desde cada colección:

• No paginar por defecto. El error más caro de esta lección: funciona en desarrollo con 10 filas y tumba producción con 100.000.
• Ordenar sin desempate único. Duplicados y elementos perdidos al paginar, de forma intermitente e irreproducible.
• Perder los filtros en los enlaces de paginación. El rel="next" debe arrastrar ordenar, filtros y campos; si no, la página 2 muestra otra cosa que la 1.
• Ignorar parámetros desconocidos en silencio. Una errata (?tuestte=medio) devuelve el catálogo entero y el cliente cree que ha filtrado.
• Permitir ordenar o filtrar por cualquier campo. Sin índice, cada consulta es un escaneo completo de la tabla.
• Recortar limite sin avisar. El cliente pide 1.000, recibe 100 y cree que la colección tiene 100.
• Dar total en paginación por cursor. Contar la colección entera anula la ventaja del cursor. Es mejor no ofrecerlo y documentarlo.
• Mezclar modelos de paginación en la misma colección sin reglas: cursor y desplazamiento a la vez deben dar 400.
• Consejo: prueba siempre con datos que cambian. Inserta filas entre la página 1 y la 2 y comprueba qué pasa. Ese experimento descubre la mitad de los bugs de paginación.
• Consejo: elige el modelo según el uso, no por moda. El cursor es superior técnicamente, pero si el panel necesita "página 7 de 12", el offset es la respuesta correcta.

Escribe la petición curl completa para cada necesidad, usando solo el contrato de esta lección:

1. Cafés de Etiopía o Colombia, con tueste claro, entre 12 y 18 euros, del más caro al más barato, 10 por página, segunda página.
2. Pedidos del cliente cli_842 pagados o enviados en marzo de 2026, los más recientes primero.
3. Reseñas pendientes de moderación con 3 estrellas o menos, mostrando solo id, puntuacion y comentario.
4. Búsqueda de "chocolate" en el catálogo, solo cafés disponibles, ordenados por precio ascendente.

El panel interno de Tienda Aroma lista pedidos así:

Los usuarios se quejan de dos cosas: (a) a veces ven el mismo pedido en dos páginas, y (b) la última página tarda ocho segundos con 400.000 pedidos.

Diagnostica cada síntoma y propón la solución concreta, indicando qué se pierde con ella.

Tienda Aroma añade /v1/eventos, el registro de eventos enviados a RápidoEnvíos (evt_9f2c, pedido.pagado, pedido.enviado…). Características: crece a razón de miles de eventos al día, nunca se modifica ni se borra, y RápidoEnvíos lo usa para reconciliar lo que ha recibido, recorriéndolo entero desde el último punto conocido.

Diseña el contrato de esta colección: modelo de paginación, parámetros, filtros, orden por defecto, metadatos y cabeceras. Justifica cada decisión.

Solución 1

Observaciones: en la 1, la segunda página con limite=10 es desplazamiento=10, y el multivalor de origen usa coma con el acento codificado. En la 3 hace falta un filtro puntuacionMax que no está en la tabla de la sección 2: la respuesta correcta incluye darse cuenta y proponer añadirlo como cambio retrocompatible, en lugar de inventarse ?puntuacion=<=3.

Solución 2

(a) Duplicados: falta el desempate. estado solo tiene tres valores, así que hay decenas de miles de empates y el motor los devuelve en orden distinto en cada consulta. Solución: el servidor añade siempre id como último criterio (ORDER BY estado, id), lo documenta y no depende de que el cliente lo pida. Coste: ninguno, salvo asegurar el índice adecuado. Es un fallo del servidor, no del cliente.

(b) Lentitud: deep paging. Con desplazamiento=399950, el motor lee y descarta 399.950 filas. Solución: paginación por cursor para /pedidos, más el tope de desplazamiento=10000. Lo que se pierde: el panel ya no podrá saltar directamente a la página 5.000 ni mostrar "página 3 de 8.000", porque el cursor solo ofrece siguiente y anterior. Mitigación práctica: casi nadie necesita la página 5.000 —lo que necesita es filtrar mejor—, así que la solución completa combina cursor y filtros por fecha y estado para que el recorrido profundo deje de ser necesario.

Solución 3

Modelo: paginación por cursor, sin ninguna duda. Los tres rasgos de la colección lo exigen: crece sin límite (el offset se degradaría), es de solo escritura y lectura secuencial (nadie necesita "la página 300"), y el caso de uso es exactamente "sigue desde donde lo dejaste", que es la definición de un cursor.

Contrato propuesto:

Ejemplo de respuesta:

Las colecciones son donde una API se enfrenta a la realidad, y ahora Tienda Aroma tiene un contrato completo para ellas: filtros explícitos por campo, rangos con Min/Max y Desde/Hasta, multivalor con comas, y el rechazo consciente a inventarse un lenguaje de consulta en la URL; ordenación con ordenar y -campo, con la regla crítica del desempate por id que hace que la paginación sea fiable; tres modelos de paginación entendidos a fondo, con offset para las colecciones estables como /cafes y cursor para las que crecen sin freno como /pedidos, más el tope de desplazamiento que evita el deep paging; los metadatos repartidos entre total en el cuerpo y la cabecera Link estándar con sus rel; búsqueda con ?q= y el criterio para saber cuándo merece recurso propio; y una tabla de valores por defecto y máximos que protege la API de sí misma.

Con esto, el contrato de la v1 está prácticamente cerrado: recursos, métodos, códigos, representaciones y colecciones. Y en cuanto un contrato se publica, empieza el problema siguiente: cambiar sin romper a nadie. En la lección siguiente, 02-07 Versionado de APIs, distinguiremos con precisión qué cambios son retrocompatibles y cuáles rompedores, compararemos las cinco estrategias de versionado —ruta, query, cabecera, media type y fecha—, justificaremos por qué Tienda Aroma versiona en /v1, y diseñaremos el ciclo de deprecación completo con las cabeceras Deprecation y Sunset.