API

Dos API

Aquí se llaman API dos cosas distintas, y no son la misma superficie.

La API local pertenece al compañero de escritorio, tcc. El daemon se ejecuta en tu propia máquina y sirve una interfaz HTTP en la dirección de loopback. Todo lo que puedes hacer en el compañero — verificar tres palabras, sellar un archivo, listar conexiones, administrar una organización — tiene una ruta. Tiene un documento OpenAPI incluido en el repositorio, que es de donde están escritas estas páginas, y el daemon sirve ese mismo documento a quien lo pida.

La API de plataforma es el lado del servidor: el servicio alojado con el que hablan las apps. No está publicada, y no lleva ninguna ruta específica de usuario — mira más abajo, porque el motivo es deliberado y no una carencia.

Qué cubre esta sección

Estas páginas cubren solo la API local. Describen dónde escucha el daemon, cómo se autentica quien llama, qué forma tienen las respuestas, y cada una de las 79 rutas documentadas.

No enseñan el compañero en sí. Instalarlo, iniciar sesión con él y ejecutarlo como daemon se cubre en las páginas del compañero y de la línea de comandos.

Por qué falta la API de plataforma

La razón corta es que no tiene documento publicado, ni versión publicada, ni promesa de estabilidad, así que páginas sobre ella describirían una superficie con la que nadie se ha comprometido a mantener.

La razón larga es la que no va a cambiar: no hay rutas específicas de usuario en la plataforma que publicar.

Responder «¿cuál es el código de María?» en un servidor significa que el servidor guarda el secreto que produce el código. En el momento en que lo hace, la promesa de extremo a extremo se acaba — no porque nadie fuera a usarlo mal, sino porque deja de ser cierta. Un servidor que PUEDE leer tus códigos es un servidor cuyo compromiso lee los códigos de todos, y ningún cuidado de nuestra parte cambia lo que se llevaría un atacante.

Así que no guardamos ningún secreto de usuario en ningún servidor que llevamos, y una API de plataforma orientada al usuario es algo que no podemos construir sin renunciar a eso. Lo que sí expone la plataforma es trabajo de nivel de sistema, de máquina a máquina, que no toca ningún secreto personal, y el titular de una cuenta no tiene acceso a eso en primer lugar.

Esto no es un hueco a la espera de llenarse. Si la API de plataforma se publica algún día, cubrirá el mismo terreno de nivel de sistema y seguirá sin tener nada tuyo.

La consecuencia para una integración: lo único que puede responder preguntas sobre las conexiones de una cuenta es algo que tiene las claves de esa cuenta — el compañero local. Guarda la sesión y las claves en tu propia máquina, hace el trabajo ahí, y habla con la plataforma para las partes que no necesitan ningún secreto. Por eso estas páginas documentan la API local, y por eso no es una segunda opción.