Saltar al contenido
Esc
↑↓navegar↵abrir⌘Jvista previa
En esta página

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=100 para 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 array data vacío por sí solo termina el recorrido sin comprobar la paginación.
  • Combine fields con 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-After en 429.
  • 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.

Páginas relacionadas

¿Te ha resultado útil esta página?