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

Recetas

Patrones prácticos de la API de Fuxam v4 — sincronizar usuarios, buscar cursos por código, actualizaciones seguras con ETag y creaciones idempotentes.

Estas recetas son patrones de extremo a extremo construidos solo con las convenciones documentadas de v4: Basic Auth, el sobre { data, meta }, paginación por cursor, Idempotency-Key y ETag / If-Match. Úselas como plantillas en su middleware; cambie las rutas de recurso según necesite y confirme los nombres de campo en las páginas de referencia de endpoints generadas.

URL base: https://fuxam.app/api/v4

Por qué ayudan las recetas

Las páginas de referencia muestran una operación a la vez. Las integraciones reales encadenan operaciones: listar → filtrar → obtener → patch, o crear → reintentar. Los patrones siguientes codifican esas secuencias para que los equipos de TI universitarios puedan desplegar trabajos de sincronización fiables sin redescubrir casos límite de concurrencia y paginación.

Antes de empezar

Receta: Sincronizar todos los usuarios

Objetivo: Extraer todos los usuarios a un sistema externo usando paginación por cursor.

Cuándo usarla: Sincronización nocturna de identidades con User Management como fuente de verdad de quién existe en Fuxam.

#!/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}&fields=id,email"
  else
    URL="${BASE}/users?limit=${LIMIT}&fields=id,email&cursor=${CURSOR}"
  fi

  RESP=$(curl -sS -u "${CLIENT_ID}:${CLIENT_SECRET}" \
    -H "Accept: application/json" "$URL")

  # Inserte o actualice cada objeto en RESP.data en su espejo SIS / directorio.
  printf '%s\n' "$RESP" | jq -c '.data[]'

  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

Pseudocódigo:

cursor = null
loop:
  response = GET /users?limit=100&fields=id,email[&cursor=cursor]
  upsert_all(response.data)
  if response.pagination.has_more is false: break
  cursor = response.pagination.next_cursor

Receta: Buscar un curso por código y leer por id

Objetivo: Resolver un código de curso legible por humanos a un id estable y obtener el recurso completo.

Cuándo usarla: Migraciones desde v3 (donde el direccionamiento por código era más habitual), importaciones SIS que solo conocen códigos de curso o enlaces a cursos que el personal gestiona en Courses Management.

CODE="CS101"

LIST=$(curl -sS -u "${CLIENT_ID}:${CLIENT_SECRET}" \
  -H "Accept: application/json" \
  "https://fuxam.app/api/v4/courses?code=${CODE}&limit=25")

COURSE_ID=$(printf '%s' "$LIST" | jq -r '.data[0].id // empty')

if [ -z "$COURSE_ID" ]; then
  echo "No course found for code ${CODE}" >&2
  exit 1
fi

curl -sS -u "${CLIENT_ID}:${CLIENT_SECRET}" \
  -H "Accept: application/json" \
  -D - \
  "https://fuxam.app/api/v4/courses/${COURSE_ID}"

Secuencia HTTP:

GET /api/v4/courses?code=CS101&limit=25 HTTP/1.1
Host: fuxam.app
Authorization: Basic <base64(clientId:clientSecret)>
Accept: application/json
GET /api/v4/courses/{id} HTTP/1.1
Host: fuxam.app
Authorization: Basic <base64(clientId:clientSecret)>
Accept: application/json

Receta: Actualizar un recurso de forma segura con ETag

Objetivo: Cambiar un solo recurso sin sobrescribir la edición concurrente de otra persona.

Cuándo usarla: Cualquier PATCH, PUT o DELETE automatizado en un solo recurso que emite ETag en GET.

USER_ID="usr_123"

# 1) Leer versión actual
HEADERS=$(mktemp)
BODY=$(mktemp)

curl -sS -u "${CLIENT_ID}:${CLIENT_SECRET}" \
  -H "Accept: application/json" \
  -D "$HEADERS" \
  -o "$BODY" \
  "https://fuxam.app/api/v4/users/${USER_ID}"

ETAG=$(awk 'BEGIN{IGNORECASE=1} /^ETag:/{print $2}' "$HEADERS" | tr -d '\r')

# 2) Escribir con If-Match
HTTP_CODE=$(curl -sS -u "${CLIENT_ID}:${CLIENT_SECRET}" \
  -o /tmp/patch-response.json -w "%{http_code}" \
  -X PATCH \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "If-Match: ${ETAG}" \
  -d @patch-body.json \
  "https://fuxam.app/api/v4/users/${USER_ID}")

if [ "$HTTP_CODE" = "412" ]; then
  echo "precondition_failed — re-GET, merge, retry" >&2
  exit 1
fi

Pseudocódigo:

resource, etag = GET /users/{id}          # capture ETag header
try:
  PATCH /users/{id} with If-Match: etag
catch 412 precondition_failed:
  resource, etag = GET /users/{id} again
  merge_changes(resource)
  retry PATCH with new etag
catch 428 precondition_required:
  ensure If-Match is sent

Receta: Crear con idempotencia

Objetivo: Crear un recurso una vez, aunque el cliente HTTP reintente tras un tiempo de espera.

Cuándo usarla: Trabajos de aprovisionamiento, consumidores de webhook que pueden entregar dos veces, cualquier creación que no deba duplicarse.

IDEMPOTENCY_KEY="$(uuidgen)"

curl -sS \
  -u "${CLIENT_ID}:${CLIENT_SECRET}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
  -d @create-body.json \
  "https://fuxam.app/api/v4/users"
POST /api/v4/users HTTP/1.1
Host: fuxam.app
Authorization: Basic <base64(clientId:clientSecret)>
Content-Type: application/json
Idempotency-Key: a1b2c3d4-e5f6-7890-abcd-ef1234567890
Accept: application/json

# Body: JSON create payload from the endpoint reference

Comportamiento esperado:

Situación Resultado
Primera creación exitosa 201 con el nuevo recurso en data
Reintento con la misma clave y creación equivalente Respuesta original en caché (incluido 201) — sin duplicado
Clave en conflicto en curso Puede devolver 409 — espere y reintente con la misma clave, o revise el manejo de conflictos en su trabajo

Receta: Manejar límites de tasa al paginar

Objetivo: Completar una sincronización grande sin fallar el trabajo al alcanzar 1000 solicitudes/min.

loop pages:
  response = GET list
  if status == 429:
    sleep(Retry-After)
    retry same request
  process response.data
  advance cursor
# Fragmento ilustrativo — respete Retry-After de los encabezados de respuesta
RETRY_AFTER=60
sleep "$RETRY_AFTER"

Combínelo con valores limit mayores para necesitar menos solicitudes por recorrido completo. Detalles: Errores e idempotencia.

Elegir un patrón

Necesidad Receta
Reflejar el directorio Sincronizar todos los usuarios
El SIS solo conoce códigos de curso Buscar por código, luego por id
Actualizar sin pisar ediciones en la interfaz Actualizar de forma segura con ETag
Aprovisionar sin duplicados Crear con idempotencia
Sincronización grande bajo carga Paginación consciente del límite de tasa

Buenas prácticas en todas las recetas

  • Registre meta.requestId en cada respuesta.
  • Prefiera trabajos del lado del servidor frente a llamadas desde el navegador con secretos de larga duración.
  • Separe integraciones por carga de trabajo para que límites de tasa y rotaciones permanezcan aislados (Autenticación).
  • Tras codificar una receta, abra la tarjeta de referencia correspondiente en la sección de exploración de la descripción general para confirmar esquemas de solicitud/respuesta.

Errores frecuentes

Error Mejor enfoque
Sincronizar con limit=1 Use hasta 100 para trabajos masivos
Crear sin Idempotency-Key Establezca siempre un UUID por creación lógica
Patch sin If-Match GET primero; envíe ETag
Asumir que el código es la clave primaria de cursos Resuelva código → id, luego use id

Preguntas frecuentes

¿Puedo adaptar estas recetas a planes de estudios o salas?

Sí — el sobre, la paginación, la autenticación, la idempotencia y las reglas ETag son compartidas. Sustituya rutas por el recurso que necesite desde las tarjetas de exploración de la descripción general (por ejemplo planes de estudios o salas) y confirme filtros en la página de referencia de ese endpoint.

¿Las recetas sustituyen la referencia OpenAPI?

No. Las recetas enseñan secuencias y convenciones. Los esquemas a nivel de campo están en las páginas de endpoints generadas como Users y Courses.

Páginas relacionadas

¿Te ha resultado útil esta página?