API

Due API

Qui due cose diverse vengono chiamate API, e non sono la stessa superficie.

L’API locale appartiene al companion desktop, tcc. Il daemon gira sulla tua stessa macchina e serve un’interfaccia HTTP sull’indirizzo di loopback. Tutto ciò che puoi fare nel companion — verificare tre parole, sigillare un file, elencare le connessioni, gestire un’organizzazione — ha una rotta. Ha un documento OpenAPI committato, che è da dove sono scritte queste pagine, e il daemon serve quello stesso documento a chi lo chiama.

L’API della piattaforma è il lato server: il servizio ospitato con cui parlano le app. Non è pubblicata, e non porta nessuna rotta specifica dell’utente — vedi sotto, perché il motivo è deliberato piuttosto che una lacuna.

Che cosa copre questa sezione

Queste pagine coprono solo l’API locale. Descrivono dove ascolta il daemon, come si autentica chi chiama, come appaiono le risposte, e ognuno dei 79 percorsi documentati.

Non insegnano il companion in sé. Installarlo, farvi l’accesso e farlo girare come daemon sono coperti dalle pagine del companion e della riga di comando.

Perché manca l’API della piattaforma

Il motivo breve è che non ha un documento pubblicato, nessuna versione pubblicata e nessuna promessa di stabilità, quindi pagine su di essa descriverebbero una superficie che nessuno si è impegnato a mantenere.

Il motivo più lungo è quello che non cambierà: non ci sono rotte specifiche dell’utente sulla piattaforma da pubblicare.

Rispondere “qual è il codice di Maria?” su un server significa che il server detiene il segreto che produce il codice. Nel momento in cui lo fa, la promessa end-to-end è finita — non perché qualcuno ne abuserebbe, ma perché smette di essere vera. Un server che PUÒ leggere i tuoi codici è un server la cui compromissione legge i codici di tutti, e nessuna quantità di cura da parte nostra cambia ciò che un aggressore porterebbe via.

Quindi non conserviamo nessun segreto utente su nessun server che gestiamo, e un’API della piattaforma rivolta all’utente è una cosa che non possiamo costruire senza rinunciarvi. Ciò che la piattaforma espone è lavoro a livello di sistema, da macchina a macchina, che non tocca nessun segreto personale, e un titolare di account comunque non vi ha accesso.

Questa non è una lacuna in attesa di essere colmata. Se l’API della piattaforma viene pubblicata un giorno, coprirà lo stesso terreno a livello di sistema e continuerà a non contenere nulla di tuo.

La conseguenza per un’integrazione: l’unica cosa che può rispondere a domande sulle connessioni di un account è qualcosa che detiene le chiavi di quell’account — il companion locale. Conserva la sessione e le chiavi sulla tua stessa macchina, svolge il lavoro lì, e parla con la piattaforma per le parti che non richiedono nessun segreto. Ecco perché queste pagine documentano l’API locale, e perché non è una seconda scelta.