Convenciones de la API · Developers
Convenciones que valen para todo endpoint de la API de Dailybot: identificadores, timestamps, casing, paginación, versionado.
Todo endpoint de la API pública de Dailybot sigue las mismas convenciones para identificadores, timestamps, casing, paginación y versionado. Aprende esto una vez y cada página de referencia se leerá exactamente como esperas.
Identificadores
Todo recurso tiene un `uuid` globalmente único (RFC 4122 v4). Los UUIDs son estables, opacos y la llave segura para usar en tu integración. Algunos recursos también tienen un `id` numérico por compatibilidad heredada — prefiere `uuid` para lo nuevo.
Timestamps
Todos los timestamps son ISO-8601 en UTC con precisión de milisegundos (p.ej. `2026-07-02T14:33:19.412Z`). Los campos que terminan en `_at` son timestamps; los que terminan en `_date` son solo fecha (`YYYY-MM-DD`). Nunca emitimos strings de hora local.
Casing de campos
Todas las claves JSON son `snake_case` (`first_name`, `created_at`). Los segmentos de path son `kebab-case` (`/pending-invitations/`, `/agent-reports/`). Los parámetros de query son `snake_case` (`include_email`, `only_active`).
Paginación
La API tiene dos estilos de paginación. `limit` + `offset` para browse clásico (users, teams, kudos). `page` + `page_size` para paginación indexada (mood, forms). Toda respuesta de lista está envuelta en `{ count, next, previous, results }`; recorre `next` hasta que sea `null`.
Versionado
La API pública se versiona por prefijo de URL (`/v1/`). Cambios aditivos (nuevos endpoints, nuevos campos opcionales, nuevos valores de enum con fallback) pueden aterrizar en cualquier momento. Los cambios rompedores viajan en un prefijo nuevo (`/v2/`) con una ventana mínima de sunset de 6 meses sobre la versión previa. Ver [/es/developers/api-changelog](/es/developers/api-changelog).
Idempotencia
Todo `GET`, `PATCH`, `DELETE` es idempotente por semántica HTTP — reintentarlos es seguro. Los `POST` que crean un recurso, en el caso general, **no** son idempotentes; un reintento ingenuo tras un blip de red puede crear recursos duplicados. Cuando reintentes tras un 5xx o error de red, primero relee el recurso por su clave natural (email, nombre, id externo) y solo re-créalo si el read devuelve 404. La política de reintentos vive en [/es/developers/errors#retry-policy](/es/developers/errors#retry-policy).
null vs. ausente
Un campo puesto en `null` significa explícitamente "este atributo no tiene valor". Un campo ausente de la respuesta significa "el llamante no tiene permiso para verlo" o "el campo no se pidió vía un include-flag". No los trates igual.