Paginación e idempotencia

Paginación por cursor en cada endpoint de listado; Idempotency-Key en cada endpoint que modifica estado. Dos patrones que interiorizar una vez; todos los endpoints los siguen.

Paginación por cursor

Todos los endpoints de listado (GET /api/v1/public/sessions, /evidence, /whiteboards, etc.) devuelven un sobre:

{
  "data": [
    { /* resource */ },
    { /* resource */ }
  ],
  "has_more": true,
  "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wNS0yMVQxNDoyMSswMDowMCJ9"
}

Cómo paginar

Emita la primera solicitud sin un parámetro cursor.
Si has_more es true, pase next_cursor textualmente como el parámetro de consulta cursor en la siguiente solicitud.
Repita hasta que has_more sea false.

curl "https://app.nexbasira.com/api/v1/public/sessions?limit=25" \
  -H "Authorization: Bearer nb_sec_..."

# response includes next_cursor: "eyJjcmVhdGVkX2F0Ijo..."

curl "https://app.nexbasira.com/api/v1/public/sessions?limit=25&cursor=eyJjcmVhdGVkX2F0Ijo..." \
  -H "Authorization: Bearer nb_sec_..."

Límites

Parámetro	Predeterminado	Máx.
`limit`	25	100

Valores de limit más altos reducen el número de idas y vueltas pero aumentan el tamaño del payload por respuesta y el tiempo de serialización. El valor predeterminado 25 es adecuado para uso de UI; los trabajos por lotes nocturnos suelen pasar 100.

Forma del cursor

El cursor es opaco para los clientes — es un blob JSON codificado en base64 que codifica la posición en el queryset subyacente. No analice ni construya cursores; simplemente páselos textualmente. La forma no es estable entre versiones de la API.

Ordenación

El orden predeterminado es created_at DESC (más reciente primero) para cada endpoint de listado. Este es también el orden en que avanza el cursor — recorrerá desde lo más reciente hasta lo más antiguo a medida que pagina.

Ayudantes del SDK

Ambos SDK incluyen un iterador asíncrono transparente que pagina por usted:

// @nexbasira/node
for await (const session of nb.sessions.list({ limit: 100 })) {
  // ...
}

// nexbasira (Python)
for session in nb.sessions.iter(limit=100):
    ...

Idempotencia

Cada endpoint que modifica estado acepta una cabecera Idempotency-Key. Pase una clave única (normalmente un UUID) por operación lógica; un reintento con la misma clave devuelve la respuesta en caché sin recrear el recurso.

curl -X POST https://app.nexbasira.com/api/v1/public/sessions \
  -H "Authorization: Bearer nb_sec_..." \
  -H "Idempotency-Key: 01HGAB7T8X3PVT3HKEXAMPLE" \
  -H "Content-Type: application/json" \
  -d '{"notes": "Vehicle damage CL-2026-0042"}'

Ventana de caché

Las respuestas en caché viven durante 24 horas. Repetir después de 24 h con la misma clave crea un nuevo recurso — trate la clave como válida solo durante la duración de su bucle de reintento.

Alcance

Las claves se limitan a (credential, endpoint, method):

Un reintento desde la misma credencial al mismo endpoint con la misma clave devuelve la respuesta en caché.
Una credencial distinta que use la misma clave crea un nuevo recurso (lo trata como una llamada nueva).
La misma clave en un endpoint distinto crea un nuevo recurso (ranura de caché independiente).

Qué se almacena en caché

Solo las respuestas correctas (2xx). Una solicitud fallida no envenena la caché — su siguiente reintento con la misma clave obtiene un intento nuevo.

Eco de cabecera

Las respuestas idempotentes correctas devuelven la clave en la cabecera de respuesta Idempotency-Key — útil para registro / correlación.

Generar claves

Use cualquier cosa que sea globalmente única por operación lógica:

crypto.randomUUID() en Node 19+
uuid.uuid4() en Python
El id de su proceso de negocio (p. ej. número de reclamación + sello de tiempo) si desea trazas legibles por humanos en los registros

Ayudantes del SDK

// @nexbasira/node — pass via second arg
await nb.sessions.create(
  { notes: "..." },
  { idempotencyKey: crypto.randomUUID() },
);

// nexbasira (Python)
nb.sessions.create(notes="...", idempotency_key=str(uuid.uuid4()))

Qué sigue

Errores y límites de tasa — qué ocurre cuando la paginación o los bucles de reintento fallan
API de sesiones — primer endpoint que aplica ambos patrones