KaiiluKaiilu

Referencia de API

Las convenciones son reales. El acceso todavía no es público.

Kaiilu no emite credenciales de API a terceros y no publica una lista de endpoints estables, porque no podemos comprometernos aún a mantenerlos. Lo que sí podemos documentar con honestidad son las convenciones que la API de Kaiilu ya sigue de forma consistente, para que sepas a qué te vas a enfrentar cuando abramos.
Solicitar accesoPortal de desarrolladores

Antes de seguir leyendo

Los endpoints bajo /api/v1 están destinados a la propia aplicación de Kaiilu. No están congelados, no tienen política de obsolescencia publicada y pueden cambiar sin aviso. Si construyes contra ellos por tu cuenta, se romperá, y no habrá una nota de migración esperándote.

Esta página describe cómo está construida la API, no te concede acceso a ella.

Modelo de autenticación

Hoy existen exactamente dos formas de autenticarse contra Kaiilu. Ninguna de las dos está disponible para terceros.

Sesión de usuario
Los endpoints de primera persona (/api/v1/me/*) resuelven la identidad a partir de la cookie de sesión del usuario. Es el modelo que usa la propia interfaz de Kaiilu. No hay intercambio de token que un cliente externo pueda ejecutar.
Secreto compartido entre servicios
La comunicación interna entre componentes de Kaiilu se autentica con un secreto compartido, enviado como cabecera y comparado en tiempo constante. Es todo o nada: no tiene ámbitos, no se puede limitar a un subconjunto de operaciones y por eso no se entrega fuera de la infraestructura de Kaiilu.
Lo que no existe
No hay claves de API por aplicación, ni OAuth, ni tokens con ámbitos, ni flujo de autorización por parte del usuario, ni refresco de credenciales. Esa es exactamente la pieza que falta construir para poder abrir.

Formato de respuesta

Consistente en toda la superficie /api/v1. Toda respuesta es JSON y lleva siempre un discriminador booleano en la raíz.

Respuesta correcta

{
  "ok": true,
  "items": [ ... ],
  "unreadCount": 3,
  "nextCursor": "clx9f2k0000abc"
}

Respuesta de error

{
  "ok": false,
  "error": "notification_list_failed"
}

El campo error es un identificador estable en snake_case, pensado para que el cliente ramifique sobre él. No es un mensaje para mostrar a una persona: nunca está traducido y no debe pintarse tal cual en una interfaz.

Códigos de estado

200
Operación resuelta. Comprueba igualmente ok: hay respuestas correctas que describen un estado desactivado en lugar de un fallo.
401
No hay sesión o falta la credencial. La petición no llegó a identificarse.
403
Identificado pero sin permiso para esta operación, o credencial inválida.
503
Una dependencia necesaria no está disponible en ese entorno. Es reintentable.
500
Fallo no previsto. Va acompañado de un error identificable y queda registrado en el servidor.

Paginación

Kaiilu pagina por cursor, no por número de página. Es la convención en toda la superficie de listados.

limit

Número de elementos por página. Valor por defecto 20, mínimo 1 y máximo 100. Los valores fuera de rango se ajustan al límite, no producen error.

cursor

Opaco. Se pasa tal cual como cursor en la siguiente petición. No interpretes su contenido ni lo construyas a mano.

nextCursor

Viene en la respuesta. Si es null, has llegado al final del listado y no hay más páginas que pedir.

Límites de uso

Kaiilu aplica control de ritmo sobre sus endpoints, pero no publicamos los umbrales. El motivo es doble: están calibrados para el uso de la propia aplicación y no para el de un cliente externo, y se ajustan según hace falta. Publicar una cifra ahora sería darte un número contra el que planificar que dejaría de ser cierto sin avisarte. Cuando exista acceso para terceros, los límites se publicarán por credencial y con cabeceras que te digan cuánto te queda.

Qué haría falta para que esta página sea una referencia de verdad

Emisión y rotación de credenciales por aplicación, permisos por ámbito, consentimiento explícito del usuario cuyos datos se leen, límites de uso por cliente con cabeceras de cuota, una política de versiones y obsolescencia por escrito, y una especificación publicada que podamos mantener. Hasta que estén las seis, esta página seguirá documentando convenciones y no endpoints.