# Gestire i FlowStream con l’API di Flow

> Accedi, elenca, crea, importa, esporta, metti in pausa, riavvia e rimuovi FlowStream con l’API JSON su /fapi/, leggi le statistiche e le variabili e chiama un flusso dall’esterno con il suo indirizzo notify o il suo percorso proxy.

Framework: flow
Product: Flow (flow@11.1)
Language: it
Content-SHA256: ee14a7f3a9ff8777449fbcab0bca80aeda2f5ec5eda405a7430e9dbcc669b6a5
Snapshot: c0700e321579725c5cf4f5ace1ad7d2866d1b4f93c24a63c0b41b6b7998e976c
Sources: 
Review: not-recorded

Tutto ciò che fa l’editor passa da un unico endpoint JSON: `POST /fapi/` con il corpo `{ "schema": "<name>", "data": { ... } }` (le rotte API di Total.js, vedi [rotte API](/en/total5/api-routes/)). L’indirizzo `/fapi/` deriva dalla riga `$api : /fapi/` del file `config`. Ogni chiamata tranne l’accesso richiede il cookie di sessione; senza di esso la risposta è `401: Unauthorized`.

Queste chiamate sono state provate anche su un Flow 11.1 locale (Node.js 24 e `total5@0.0.19`) mentre scrivevamo questa pagina.

## Accedere

`Auth|login` riceve `login` e `password` e risponde `{"success":true}` con il cookie di sessione. Una coppia errata risponde `Invalid credentials`.

```bash
curl -c cookie.txt -X POST http://localhost:8000/fapi/ \
  -H 'content-type: application/json' \
  -d '{"schema":"Auth|login","data":{"login":"<your login>","password":"<your password>"}}'
```

Le chiamate successive usano `-b cookie.txt`.

## Le chiamate

| `schema` | `data` | Cosa fa |
|---|---|---|
| `Streams` | nessuno | l’elenco dei FlowStream con `id`, `name`, `group`, `author`, `version`, `proxypath`, `size` e le `stats` in tempo reale di quelli in esecuzione |
| `Streams\|save` | `name`, e facoltativamente `author`, `version`, `icon`, `color`, `group`, `url`, `reference`, `readme`, `memory`, `cloning`, `proxypath`, `proxytimeout` | **crea** un flusso quando manca `id` (si controlla il permesso *create*), altrimenti aggiorna il flusso con quell’`id` e lo riavvia |
| `Streams\|read` | `id` | le proprietà di un flusso |
| `Streams\|raw` | `id` | l’intero oggetto del flusso, con il suo design |
| `Streams\|export` | `id` | il flusso come testo JSON in `value`, senza i campi interni (`unixsocket`, `env`, `import`, `worker`, `asfiles`) |
| `Streams\|import` | `data` (il testo JSON) | crea un **nuovo** flusso da un’esportazione (fino a 10 MB), con un nuovo `id`; un `proxypath` ripetuto viene sostituito con uno casuale; risponde `{"success":true,"value":"<id>"}` |
| `Streams\|pause` | `id`, `is` (`true` o `false`) | mette in pausa o riprende un flusso in esecuzione |
| `Streams\|restart` | `id` | riavvia il flusso |
| `Streams\|remove` | `id` | rimuove il flusso e la sua cartella (si controlla il permesso *remove*) |
| `Streams\|stats` | nessuno | i totali dell’installazione: versioni di Node.js, Total.js e Flow, messaggi, in attesa, memoria e connessioni |
| `Variables\|read` / `Variables\|save` | `id` (facoltativo), `data` | le variabili di un flusso, oppure le variabili **globali** quando `id` è vuoto; il salvataggio le invia ai flussi in esecuzione |
| `Console\|read` / `Console\|clear` | nessuno | la console dell’applicazione |
| `CDN\|clear` | nessuno | svuota la cache dei componenti dell’interfaccia scaricati |
| `Settings\|read` / `Settings\|save` | le impostazioni (vedi [impostazioni e file](/en/flow/settings-and-files/)) | solo per il super amministratore |

## Creare un flusso ed eseguirlo

Crealo, poi importa un design costruito nell’editor (un file JSON esportato) per avviarlo:

```bash
curl -b cookie.txt -X POST http://localhost:8000/fapi/ \
  -H 'content-type: application/json' \
  -d '{"schema":"Streams|save","data":{"name":"Demo","author":"Me"}}'
```

Un flusso esportato dall’editor porta con sé il suo `design` (i riquadri e le loro connessioni), i suoi `components` (il sorgente di ciascuno) e le sue `variables`.

## Regole di `proxypath`

Un flusso può pubblicare rotte HTTP sotto un percorso proprio. Flow aggiunge le barre (`demo` diventa `/demo/`), rifiuta i percorsi che appartengono a Flow stesso (`/`, `/cdn/`, `/fapi/`, `/private/`, `/flows/`, `/designer/`, `/parts/`, `/forms/`, `/css/`, `/js/`, `/fonts/`, `/panels/`) con `Proxy endpoint contains reserved path` e rifiuta un percorso già usato da un altro flusso. `proxytimeout` è il tempo in secondi di attesa della risposta del flusso (il valore predefinito è `120`).

## Chiamate dall’esterno

| Rotta | Uso |
|---|---|
| `GET` o `POST /notify/{id}/` | invia una notifica al flusso con quell’id (il corpo del POST è limitato a 1 MB); i componenti del flusso decidono cosa farne. Risponde `{"success":true}` |
| `+SOCKET /{id}/` | il WebSocket dell’editor per quel flusso (richiede la sessione) |
| `GET /private/?token=<token>` | elenca i file della cartella `private/` quando il token coincide con il `token` delle impostazioni; dieci token errati bloccano un indirizzo per 15 minuti |
| `+POST /update/` | aggiorna l’applicazione da un file `.bundle`; solo per la versione impacchettata |

Tieni segreto il `token`, invia queste chiamate via HTTPS e metti Flow dietro un reverse proxy quando è raggiungibile da Internet.