O que é o Systemplane
O Systemplane não é um serviço autônomo. Cada aplicação monta o mesmo conjunto de rotas em seu próprio host e porta HTTP sob um prefixo de caminho específico da aplicação — não há host nem porta dedicados ao Systemplane, e nenhuma porta de administração dedicada. O prefixo canônico documentado aqui é
/system, mas ele varia por aplicação (veja a tabela de aplicabilidade abaixo).
Como as rotas são registradas programaticamente em vez de emitidas por um gerador de código, elas não aparecem na referência de API gerada de cada produto. Esta referência documenta a superfície manualmente para que você a opere de forma consistente entre os produtos.
Toda a superfície fica desativada por padrão. Uma aplicação só a atende quando a configuração SYSTEMPLANE_ENABLED está ativada; caso contrário, a aplicação roda em modo somente variáveis de ambiente e essas rotas não são montadas.
Namespaces
A configuração é organizada em namespaces, cada um contendo entradas planas com chaves em string. Trilhos e plugins usam três namespaces canônicos:
Algumas aplicações registram um único namespace com o nome da aplicação em vez desses três. O Matcher, por exemplo, mantém todas as suas chaves sob um único namespace
matcher.
O valor de cada entrada é sem tipo na camada de transporte: cada chave registrada aceita seu próprio escalar, objeto ou array JSON, validado pelo validador do lado do servidor daquela chave. Nem toda configuração é alterável em tempo de execução — configurações somente de bootstrap são lidas uma única vez na inicialização, não são registradas no Systemplane e ainda exigem reinício para serem alteradas.
Endpoints
Todos os caminhos são relativos ao prefixo da aplicação (padrão
/system).
/system/-/catalog é um caminho de metadados reservado, atendido antes das rotas de namespace — - não é um namespace real e não pode ser usado como um. Os erros usam um envelope plano {"code": <int>, "title": "<string>", "message": "<string>"}.Autenticação e permissões
A autorização é negar tudo por padrão. Uma aplicação só atende a superfície depois de ser configurada com um autorizador; sem um, toda requisição é negada. Quando a autenticação está ativada, a aplicação aplica controle de acesso baseado em papéis por namespace sobre uma identidade válida com escopo de plataforma (não de tenant). As leituras exigem a permissão de leitura do namespace e as escritas exigem a permissão de escrita correspondente:
A ação de leitura cobre
GET; a ação de escrita cobre PUT e DELETE. Os endpoints de descoberta do catálogo exigem permissão de leitura para pelo menos um namespace.
As strings exatas de permissão podem variar por aplicação. O Matcher, que usa um único namespace, protege toda a sua superfície com a permissão
system-runtime-config:admin (recurso system-runtime-config, ação admin) em vez das strings por namespace acima. Consulte a documentação do próprio produto para conhecer seu modelo de autorização.Descobrindo chaves com o catálogo
Quando uma aplicação opta pela superfície de catálogo,
GET /system/-/catalog lista todas as chaves que ela registra, e GET /system/-/catalog/{namespace}/{key} retorna o contrato de escrita completo de uma chave — seu tipo, escopo de tenant, classe de tempo de execução, política de redação, esquema JSON, regras de validação, exemplos válidos, valor padrão e o caminho PUT correspondente.
Use o catálogo para descobrir o que um serviço expõe antes de alterar qualquer coisa: o catálogo descreve o contrato de escrita, enquanto o valor configurado atual é lido a partir de GET /system/{namespace}/{key}.
Quais produtos expõem o Systemplane
O Systemplane é opcional por produto. A tabela abaixo lista os produtos que o montam, o prefixo de caminho que cada um usa, sua porta HTTP padrão e se ele também atende a superfície de descoberta do catálogo. O prefixo e a porta são padrões — uma implantação pode sobrescrevê-los.
Produtos não listados aqui não montam o Systemplane — eles são configurados apenas por variáveis de ambiente.