# Gerir FlowStreams com a API do Flow

> Inicie sessão, liste, crie, importe, exporte, pause, reinicie e remova FlowStreams com a API JSON em /fapi/, leia as estatísticas e as variáveis e chame um fluxo a partir de fora com o seu endereço notify ou o seu próprio caminho proxy.

Framework: flow
Product: Flow (flow@11.1)
Language: pt
Content-SHA256: 86a4e8331ec4bbe2ff82693a2801b2b3c361b4570baa266625b4955ea4c9ec65
Snapshot: c0700e321579725c5cf4f5ace1ad7d2866d1b4f93c24a63c0b41b6b7998e976c
Sources: 
Review: not-recorded

Tudo o que o editor faz passa por um único endpoint JSON: `POST /fapi/` com o corpo `{ "schema": "<name>", "data": { ... } }` (as rotas API do Total.js, veja [rotas API](/en/total5/api-routes/)). O endereço `/fapi/` vem da linha `$api : /fapi/` do ficheiro `config`. Todas as chamadas exceto o início de sessão precisam do cookie de sessão; sem ele a resposta é `401: Unauthorized`.

Estas chamadas também foram testadas contra um Flow 11.1 local (Node.js 24 e `total5@0.0.19`) enquanto esta página era escrita.

## Iniciar sessão

`Auth|login` recebe `login` e `password` e responde `{"success":true}` com o cookie de sessão. Um par errado responde `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>"}}'
```

As chamadas seguintes usam `-b cookie.txt`.

## As chamadas

| `schema` | `data` | O que faz |
|---|---|---|
| `Streams` | nenhum | a lista de FlowStreams com `id`, `name`, `group`, `author`, `version`, `proxypath`, `size` e as `stats` em direto dos que estão a correr |
| `Streams\|save` | `name`, e opcionalmente `author`, `version`, `icon`, `color`, `group`, `url`, `reference`, `readme`, `memory`, `cloning`, `proxypath`, `proxytimeout` | **cria** um fluxo quando falta `id` (verifica-se a permissão *create*); caso contrário atualiza o fluxo com esse `id` e reinicia-o |
| `Streams\|read` | `id` | as propriedades de um fluxo |
| `Streams\|raw` | `id` | o objeto completo do fluxo, com o seu design |
| `Streams\|export` | `id` | o fluxo como texto JSON em `value`, sem os campos internos (`unixsocket`, `env`, `import`, `worker`, `asfiles`) |
| `Streams\|import` | `data` (o texto JSON) | cria um fluxo **novo** a partir de uma exportação (até 10 MB), com um `id` novo; um `proxypath` repetido é substituído por um aleatório; responde `{"success":true,"value":"<id>"}` |
| `Streams\|pause` | `id`, `is` (`true` ou `false`) | pausa ou retoma um fluxo em execução |
| `Streams\|restart` | `id` | reinicia o fluxo |
| `Streams\|remove` | `id` | remove o fluxo e a sua pasta (verifica-se a permissão *remove*) |
| `Streams\|stats` | nenhum | os totais da instalação: versões do Node.js, Total.js e Flow, mensagens, pendentes, memória e ligações |
| `Variables\|read` / `Variables\|save` | `id` (opcional), `data` | as variáveis de um fluxo, ou as variáveis **globais** quando `id` está vazio; ao gravar são enviadas aos fluxos em execução |
| `Console\|read` / `Console\|clear` | nenhum | a consola da aplicação |
| `CDN\|clear` | nenhum | limpa a cache dos componentes da interface descarregados |
| `Settings\|read` / `Settings\|save` | as definições (veja [definições e ficheiros](/en/flow/settings-and-files/)) | apenas para o superadministrador |

## Criar um fluxo e executá-lo

Crie-o e depois importe um design construído no editor (um ficheiro JSON exportado) para o iniciar:

```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"}}'
```

Um fluxo exportado do editor leva o seu `design` (as caixas e as suas ligações), os seus `components` (o código de cada um) e as suas `variables`.

## Regras de `proxypath`

Um fluxo pode publicar rotas HTTP sob um caminho próprio. O Flow acrescenta as barras (`demo` passa a `/demo/`), rejeita os caminhos que pertencem ao próprio Flow (`/`, `/cdn/`, `/fapi/`, `/private/`, `/flows/`, `/designer/`, `/parts/`, `/forms/`, `/css/`, `/js/`, `/fonts/`, `/panels/`) com `Proxy endpoint contains reserved path` e rejeita um caminho que outro fluxo já use. `proxytimeout` é o tempo em segundos a esperar pela resposta do fluxo (a predefinição é `120`).

## Chamadas a partir de fora

| Rota | Utilização |
|---|---|
| `GET` ou `POST /notify/{id}/` | envia uma notificação ao fluxo com esse id (o corpo do POST está limitado a 1 MB); os componentes do fluxo decidem o que fazer com ela. Responde `{"success":true}` |
| `+SOCKET /{id}/` | o WebSocket do editor para esse fluxo (precisa da sessão) |
| `GET /private/?token=<token>` | lista os ficheiros da pasta `private/` quando o token é igual ao `token` das definições; dez tokens errados bloqueiam um endereço durante 15 minutos |
| `+POST /update/` | atualiza a aplicação a partir de um ficheiro `.bundle`; apenas para a versão empacotada |

Mantenha o `token` em segredo, envie estas chamadas por HTTPS e ponha o Flow atrás de um proxy inverso quando estiver acessível a partir da Internet.