Paginación y filtrado
Paginación por cursor, conjuntos de campos dispersos y patrones de filtrado para endpoints de lista de la API de Fuxam v4 — limit, cursor, fields y filtros por código.
Los endpoints de lista en la API de Fuxam v4 devuelven páginas de resultados dentro del sobre compartido { data, pagination, meta }. Se recorre una colección con cursores opacos, opcionalmente se reduce cada carga con conjuntos de campos dispersos y, en recursos compatibles, se acotan resultados con filtros como el code del curso.
Por qué importa
Los directorios de instituciones son grandes. Obtener todos los usuarios o cursos en una respuesta no es fiable ni respetuoso con el presupuesto compartido de 1000 solicitudes/min. La paginación por cursor ofrece páginas estables y eficientes; los conjuntos de campos dispersos reducen el ancho de banda; los filtros permiten resolver un curso conocido sin recorrer todo el catálogo.
Cómo encaja
Esta página se apoya en las convenciones de la descripción general y la llamada de primera página en Primeros pasos. El comportamiento de límite de tasa al paginar de forma agresiva se cubre en Errores e idempotencia.
Conceptos clave
| Término | Definición |
|---|---|
| Cursor / keyset pagination | Las páginas se identifican por un cursor opaco sobre (sortField, id), no por offsets numéricos. |
| limit | Parámetro de consulta de tamaño de página: 1–100. Se aplica el valor por defecto del servidor si se omite. |
| cursor | Token opaco de pagination.next_cursor de la página anterior. |
| has_more | Cuando es false, ha llegado a la última página. |
| Sparse fieldset | ?fields= con los nombres de propiedad que desea devueltos. |
| Filter | Parámetros de consulta específicos del recurso (por ejemplo code en cursos). |
Referencia de paginación por cursor
| Parámetro | Ubicación | Descripción |
|---|---|---|
limit |
Consulta | Tamaño de página (1–100) |
cursor |
Consulta | Cursor opaco del pagination.next_cursor de la página anterior |
pagination.next_cursor |
Respuesta | Páselo como cursor en la siguiente solicitud cuando existan más páginas |
pagination.has_more |
Respuesta | true si hay otra página disponible |
pagination.limit |
Respuesta | Tamaño de página efectivo de esta respuesta |
Ejemplo de respuesta de lista:
{
"data": [{ "id": "usr_123" }, { "id": "usr_456" }],
"pagination": {
"next_cursor": "eyJpZCI6MTIzfQ==",
"has_more": true,
"limit": 25
},
"meta": {
"requestId": "req_1700000000000_abc123",
"timestamp": "2026-01-15T10:30:00.000Z",
"version": "v4"
}
}
Seguridad de cursores
Los cursores están firmados con HMAC y ligados a su institución e integración. Cursores manipulados, caducados en sentido o ajenos devuelven HTTP 400 con código invalid_cursor. Nunca comparta cursores entre integraciones ni edite su contenido.
Cómo recorrer todas las páginas
Pseudocódigo para una sincronización de colección completa:
#!/usr/bin/env bash
set -euo pipefail
BASE="https://fuxam.app/api/v4"
CURSOR=""
LIMIT=100
while true; do
if [ -z "$CURSOR" ]; then
URL="${BASE}/users?limit=${LIMIT}"
else
URL="${BASE}/users?limit=${LIMIT}&cursor=${CURSOR}"
fi
RESP=$(curl -sS -u "${CLIENT_ID}:${CLIENT_SECRET}" -H "Accept: application/json" "$URL")
# Procese RESP.data en el lenguaje que elija, luego:
HAS_MORE=$(printf '%s' "$RESP" | jq -r '.pagination.has_more')
CURSOR=$(printf '%s' "$RESP" | jq -r '.pagination.next_cursor // empty')
if [ "$HAS_MORE" != "true" ]; then
break
fi
done
Forma HTTP para páginas posteriores:
GET /api/v4/users?limit=100&cursor=eyJpZCI6MTIzfQ== HTTP/1.1
Host: fuxam.app
Authorization: Basic <base64(clientId:clientSecret)>
Accept: application/json
Conjuntos de campos dispersos
En endpoints compatibles, solicite solo los campos que necesita:
GET /api/v4/users?fields=id,email&limit=50 HTTP/1.1
Host: fuxam.app
Authorization: Basic <base64(clientId:clientSecret)>
Accept: application/json
curl -sS \
-u "${CLIENT_ID}:${CLIENT_SECRET}" \
-H "Accept: application/json" \
"https://fuxam.app/api/v4/users?fields=id,email&limit=50"
Beneficios:
- Cargas más pequeñas al sincronizar directorios grandes
- Contratos más claros en clientes tipados (documenta los campos de los que depende)
- Menos acoplamiento accidental a propiedades que no usa
Filtrado
Los filtros son específicos del recurso. Un ejemplo documentado y habitual es buscar cursos por code y luego direccionarlos por id en llamadas posteriores (importante si migra desde v3).
GET /api/v4/courses?code=CS101&limit=25 HTTP/1.1
Host: fuxam.app
Authorization: Basic <base64(clientId:clientSecret)>
Accept: application/json
curl -sS \
-u "${CLIENT_ID}:${CLIENT_SECRET}" \
-H "Accept: application/json" \
"https://fuxam.app/api/v4/courses?code=CS101&limit=25"
Seguimiento típico: tome data[0].id de la lista filtrada, luego GET /courses/{id} para el sobre completo de un solo recurso (y ETag si va a actualizarlo). Consulte Recetas para el patrón de extremo a extremo y Courses para la referencia de la operación de lista.
Los cursos en el manual web son las mismas entidades que el personal explora en Courses Management y abre en el LMS.
Buenas prácticas
- Prefiera
limit=100para trabajos de sincronización masiva; use límites menores al explorar de forma interactiva. - Deténgase estrictamente en
has_more === false— no asuma que un arraydatavacío por sí solo termina el recorrido sin comprobar la paginación. - Combine
fieldscon paginación cuando solo necesite ids para una tabla de unión. - Respete los límites de tasa al recorrer muchas páginas; honre
Retry-Afteren429. - Trate los cursores como secretos opacos de su integración — no los registre en canales públicos.
Errores frecuentes
| Error | Resultado | Remedio |
|---|---|---|
Usar page / pageSize de v3 |
Errores inesperados o parámetros ignorados | Cambie a cursor / limit |
| Reutilizar el cursor de otra integración | 400 invalid_cursor |
Inicie una lista nueva con sus propias credenciales |
| Asumir estabilidad de offset | Filas duplicadas o faltantes con escrituras concurrentes | Los cursores keyset ya reducen esto; diseñe sincronizaciones para consistencia eventual |
| Obtener objetos completos cuando solo necesita ids | Sincronizaciones lentas, mayor uso de tasa | Use ?fields=id (y otras claves necesarias) |
Preguntas frecuentes
¿Cuál es el tamaño máximo de página?
limit acepta 1–100. Los valores fuera de ese rango deben tratarse como errores del cliente — manténgase en el rango documentado.
¿Puedo saltar a la página 10?
No. La paginación por cursor no admite números de página arbitrarios. Avance desde el inicio o conserve un cursor almacenado de una ejecución anterior del mismo recorrido.
¿Todos los endpoints de lista admiten los mismos filtros?
No. Los filtros son por recurso. Use code en cursos según la documentación; consulte la página de referencia de cada endpoint para otros parámetros de consulta.