---
title: Gerenciamento pela API HTTP
url: https://doc2.pstreamer.tv/pt/manual/extras/api.html
lang: pt-BR
product: Perfect Streamer
version: 2.0.1.264
---

# Gerenciamento pela API HTTP

Tudo o que a interface web faz, o nó sabe fazer por uma requisição de fora: a API HTTP lê e altera a configuração do serviço em funcionamento e devolve o seu estado. Junto com a interface web, são as únicas interfaces que aplicam uma alteração imediatamente e informam o resultado.

A página dá uma visão geral: onde fica a API, como ela é organizada, como chegam os erros e em que difere de editar o arquivo de configuração. A referência de cada requisição e de cada chave está em documentos separados (Documentos de referência); aqui ela não é repetida.

## Acesso

A API responde no mesmo servidor web que a interface de administração. Na configuração fornecida é a porta `8808`; se nenhuma porta estiver indicada nas configurações, o serviço usa o valor interno `43971`. A porta TLS é `43981`, mas logo após a instalação o TLS está desligado e essa porta não é escutada ([Configurações iniciais](../first_start/index.md#first-start-initial-settings)). A API não tem endereço nem prefixo próprio do tipo */api*.

- **HTTP e HTTPS são equivalentes.** O redirecionamento da porta aberta para TLS afeta apenas as páginas da interface; as requisições da API continuam funcionando por ambos os protocolos.
- **A autenticação é HTTP Digest**, com as mesmas contas da interface web e os mesmos papéis: **Admin** — acesso total, **Restricted admin** — ler tudo e pausar um fluxo, sua entrada ou sua saída, **Viewer** — somente leitura. Uma gravação feita fora do próprio papel é recusada. Em lugar da senha, a sessão pode ser apresentada com uma chave de login automático — cookie, cabeçalho `X-Auth-Token` ou parâmetro `?auth-token=`.
- **As requisições do próprio nó não são autenticadas.** Uma chamada que chegou pela interface de loopback (`127.0.0.1`, `::1`) passa sem Digest e recebe o papel **Admin**. Isso não pode ser desligado; não existe configuração para tal. A concessão tem limites: ela não pode ser reivindicada de fora do nó — atribuir-se um endereço de loopback por um cabeçalho não funciona — e é retirada para uma requisição entre origens, pois do contrário uma página web aberta no nó comandaria toda a API através do `127.0.0.1` sem credencial alguma.

  Há uma única consequência diante da qual agir: qualquer processo no nó dispõe da configuração sem senha. Se um proxy reverso for colocado à frente da API, aponte-o para um endereço não loopback do mesmo nó — então a autenticação funciona normalmente. Um proxy que acessa o `127.0.0.1` distribui acesso total a todos cujas requisições ele repassa.
- **Há apenas dois métodos** — `GET` e `POST`. A qualquer outro método chega a resposta «método não suportado»; a exceção é a requisição prévia `OPTIONS` do navegador, à qual o servidor responde com uma permissão se a origem da requisição for admitida.

> **Aviso**
>
> **O papel restringe apenas a escrita.** A verificação do papel é feita para as requisições `POST`; a leitura não é restringida por nada, e os valores voltam como estão, sem mascaramento. Uma conta com o papel **Viewer** vê todas as senhas, os segredos do Meshwork, as frases secretas dos transportes e as chaves de proteção de conteúdo — e exportar uma cópia de segurança das configurações também é uma leitura, ou seja, toda a configuração em uma única requisição. O papel **Viewer** limita a possibilidade de alterar o nó, não o acesso aos seus segredos: crie-o sabendo disso.

A distribuição dos fluxos e do guia de programação funciona em portas próprias e não gerencia as configurações ([Configurações iniciais](../first_start/index.md#first-start-initial-settings)).

## De que a API é composta

| Família | Finalidade |
| --- | --- |
| `/config/…` | Leitura e alteração da configuração. A árvore de requisições repete, no essencial, a estrutura do arquivo de configuração: uma seção do arquivo é um nó da árvore ([Estrutura do documento](config_file.md#extras-config-file-structure)). Há divergências: o array de armazenamentos do arquivo é endereçado como `/config/dvr-storage` e os conjuntos de canais do guia de programação como `/config/epg-channel-set`, embora no arquivo eles fiquem dentro de `dvr-storage-list` e de `epg-server`. |
| `/data/…` | O estado do serviço em funcionamento, sobretudo para leitura: os fluxos e suas cadeias, o equipamento, o guia de programação, o monitor do sistema, o log, as informações da licença. Algumas requisições alteram o estado — zerar as estatísticas, iniciar uma varredura, baixar um alerta; dessas, apenas uma altera a configuração: retirar um peer Meshwork da visão geral do domínio. Há exemplos prontos de requisições em [Grelha diária em JSON](../streamer/epg/middleware.md#streamer-epg-json) e [Assistente de reclamações](../streamer/analyzer.md#streamer-analyzer-ai). |
| `/schema/…` | Listas de referência em formato JSON, somente para leitura: os tipos de entrada e de saída suportados por esta compilação, os idiomas, as placas de recepção e os dispositivos de transcodificação encontrados, a escala de importância e os códigos de alarme. Não têm relação com o arquivo de esquema das configurações ([Verificação pelo JSON Schema](config_file.md#extras-config-file-schema)). |
| Endereços avulsos | Algumas requisições de serviço fora dessas árvores: reiniciar o serviço, exportar e restaurar uma cópia de segurança das configurações, a lista de interfaces de rede, encerrar a sessão. |

## Como chegam os erros

Um erro de nível de aplicação é devolvido pela API com **código HTTP 200** e um campo `result` diferente de zero no corpo da resposta: um valor fora da faixa, uma verificação recusada, uma tentativa de gravar uma chave imutável, a recusa de gravar uma chave inacessível a esse papel.

Um script que verifica apenas o código HTTP tomará, portanto, todas essas recusas por sucessos, uma após a outra. Analise o corpo da resposta.

Códigos diferentes de 200 também ocorrem, mas significam outra coisa: 401 — a autenticação não passou, 403 — o papel não é admitido à própria requisição, 404 — não existe tal requisição, 405 — o método não é suportado. Uma recusa por papel chega, assim, de duas maneiras diferentes: a requisição inteira é rejeitada com o código 403, enquanto uma chave isolada não admitida volta em uma resposta comum com um `result` diferente de zero.

Um valor fora da faixa permitida a API **rejeita**. É nisso que ela difere da leitura do arquivo de configuração, onde esse valor é levado ao limite da faixa ([É aceito, mas não como pretendia quem editou](config_file.md#extras-config-file-tolerated)).

Uma chave desconhecida a API não rejeita: ela é ignorada exatamente como na leitura do arquivo, a resposta chega com `result` 0 e o único rastro fica no log do nó. Por isso um erro de digitação no nome de uma chave também não é visto aqui — os nomes das chaves são verificados de antemão pelo esquema ([Verificação pelo JSON Schema](config_file.md#extras-config-file-schema)).

## Alterações que exigem um reinício

Duas alterações só entram em vigor após reiniciar o serviço: a ativação da licença e a restauração das configurações a partir de uma cópia de segurança. Nenhuma das duas deixa o reinício a critério do operador: aceito o arquivo, o serviço se reinicia sozinho depois de cerca de quatro segundos — não dá para adiar, e durante o reinício o nó fica indisponível. As respostas dessas duas requisições não trazem o campo `reboot`; nas respostas JSON da API de configuração ele significa que o nó já está indo para o reinício, e não que o reinício aguarda um comando. Do mesmo modo, por si só, reinicia-se o nó cuja licença expirou. Reiniciar o serviço por vontade própria é possível com uma requisição separada, pela interface web ou com o comando `sudo systemctl restart pss`.

Alterar as portas de escuta e ligar o TLS não exigem reiniciar o serviço: ele fecha o socket de escuta e o abre de novo, e não haverá campo `reboot` na resposta. As conexões abertas nessa porta são rompidas nesse momento, e daí em diante é preciso conectar-se já na nova porta.

## A API ou o arquivo de configuração

|  | HTTP API | O arquivo `pss.json` |
| --- | --- | --- |
| Quando entra em vigor | Imediatamente | A partir da próxima inicialização do serviço |
| Estado do serviço | Em funcionamento | Parado |
| Resultado | É devolvido na resposta | Visível apenas no log após a inicialização |
| Valor fora da faixa | É rejeitado | É levado ao limite |
| Chave desconhecida | Ignorada em silêncio, `result` 0 | Ignorada em silêncio, a menos que se leia o log |
| Para que é conveniente | Alterações pontuais, automação, observação | Edições em massa, transferência das configurações entre nós e versões |

Editar o arquivo de um serviço em funcionamento é inútil e perigoso: o serviço sobrescreve o `pss.json` com o que mantém na memória, e faz isso conforme o seu próprio cronograma — a edição desaparecerá sem uma única mensagem. Pare o serviço e verifique o arquivo pelo esquema antes de iniciá-lo; o procedimento está em [Editar, verificar e transferir as configurações](config_editing.md#extras-config-editing).

## Documentos de referência

| Documento | Conteúdo |
| --- | --- |
| `http_config_api.txt` | A referência da API de configuração: o protocolo, as operações, a árvore `/config` e a descrição item a item de cada chave — tipo, restrições, valor padrão. |
| `http_data_api.txt` | A referência da API de estado e estatísticas: a árvore `/data`, os formatos de resposta, as requisições ao log e às bases. |
| `pss_config_file.txt` | A referência do formato do arquivo de configuração. A sua exposição para o operador é [O arquivo de configuração pss.json](config_file.md#extras-config-file). |
| `pss_config_editing.txt` | Os procedimentos de edição, verificação e transferência das configurações. A sua exposição é [Editar, verificar e transferir as configurações](config_editing.md#extras-config-editing). |
| `pss.schema.json`, `pss.compat.schema.json` | Uma descrição legível por máquina do arquivo de configuração em formato JSON Schema ([Verificação pelo JSON Schema](config_file.md#extras-config-file-schema)). |

Os documentos são escritos em inglês. Eles não fazem parte do pacote: não estão no nó e não é preciso procurá-los lá.

Tudo isso está publicado no site da documentação, com um diretório para cada versão do produto:

```
https://doc2.pstreamer.tv/reference/      quatro documentos de referência
https://doc2.pstreamer.tv/schema/         dois esquemas
```

Use o diretório da versão que você tem instalada: a referência de outra edição não descreve o seu nó.

> **Aviso**
>
> **A compatibilidade retroativa não é garantida.** Uma atualização pode alterar tanto a API HTTP quanto o esquema e o formato do arquivo de configuração: a composição e os nomes das chaves, as faixas de valores, a forma das requisições e das respostas. Verifique novamente os scripts que trabalham com a API após cada atualização, e pegue os documentos de referência e o esquema da mesma versão da compilação instalada.

Disso decorrem três regras para quem escreve a sua própria integração:

- **Vincule-se à versão** para a qual o script foi escrito, e verifique-a na inicialização.
- **Leia de volta depois de gravar.** Uma chave que já não existe na nova compilação não é recusada, e sim ignorada, e a resposta informa sucesso: justamente a requisição que apanharia esse desaparecimento é a que não o apanha.
- **Um atributo ausente na resposta significa «esta versão não o informa», e não zero.** Caso contrário, um indicador removido ou renomeado numa atualização transforma-se numa medição verossímil de algo que não existe.