API Administrativa e Monitor Web (OpenAPI 3.1)¶
Versão da especificação: 1.0.0 · Endpoints: 69 · Operações: 72 · Schemas: 28
Baixar especificação OpenAPI YAML
API REST do Monitor Web do Nucleo Federado (federated-rest-api / AdminWebServer, porta 8088). Usada pelo dashboard (renderizado no proprio servidor), por operadores/ pesquisadores via integracao direta e por ferramentas externas. Nenhum dado bruto de sensor/observacao e exposto por esta API — apenas contratos, consentimentos (LGPD), rodadas, artefatos, metricas e hashes ja registrados no ledger. O servidor nao aplica autenticacao HTTP propria. Restrinja o acesso a rede confiavel e configure HTTPS/TLS no monitor antes de expor endpoints administrativos ou uploads. Esta especificacao documenta as rotas administrativas e de monitoramento implementadas por AdminWebServer. A API client-facing dos participantes esta no arquivo openapi-hdt-client.yaml. Endpoints chamados pelos proprios participantes HDT (Docker/Android) — anuncio, consentimento automatico, status CDDL e download do pacote DEX — estao documentados separadamente em openapi-hdt-client.yaml.
Endpoints por Domínio¶
system¶
Saude, metadados e a propria documentacao da API
| Método | Caminho | operationId |
Resumo |
|---|---|---|---|
GET |
/health |
health |
Verifica a saude do monitor e do ledger Fabric |
GET |
/api/status |
apiStatus |
Estado das conexoes MQTT/Hyperledger para o indicador visual do dashboard |
GET |
/openapi.json |
openapiJson |
Resumo desta especificacao em JSON (subconjunto; ver /openapi.yaml para o spec completo) |
GET |
/openapi.yaml |
openapiYaml |
Especificacao OpenAPI 3.1 completa (esta mesma especificacao) |
GET |
/swagger-ui |
swaggerUi |
Console Swagger UI interativo (tambem atende /swagger-ui/; le /openapi.yaml) |
monitoring¶
Estado consolidado, metricas, containers Docker e configuracao de simulacao
| Método | Caminho | operationId |
Resumo |
|---|---|---|---|
GET |
/api/events/stream |
streamMonitorEvents |
Recebe eventos do monitor em tempo real por Server-Sent Events |
POST |
/api/experiments/{experimentId}/config |
updateExperimentConfig |
Recebe parametros do comando de configuracao legado |
POST |
/api/experiments/{experimentId}/create-participants |
createDockerParticipants |
Agenda criacao de participantes Docker para experimentos compativeis |
POST |
/api/experiments/{experimentId}/destroy-participants |
destroyDockerParticipants |
Encerra participantes Docker do experimento |
POST |
/api/experiments/{experimentId}/run-experiment |
runExperimentFlow |
Executa o fluxo completo de um experimento |
GET |
/api/experiments/{experimentId}/performances |
listPerformances |
Lista pontos de desempenho por rodada |
GET |
/api/experiments/{experimentId}/models |
listModels |
Lista versoes do modelo global |
GET |
/api/experiments/{experimentId}/models/{version}/content |
getModelContent |
Baixa o conteudo (CSV do vetor) de uma versao do modelo global |
GET |
/api/experiments/{experimentId}/assets |
listAssets |
Lista evidencias auditaveis do ledger |
GET |
/api/experiments/{experimentId}/state |
getExperimentState |
Estado operacional canonico do experimento |
GET |
/api/experiments/{experimentId}/tasks |
listExperimentTasks |
Lista tarefas em segundo plano do experimento (deploys, replays, execucoes) e seu status |
GET |
/api/experiments/{experimentId}/containers |
listExperimentContainers |
Lista containers Docker (cliente/agregador) do experimento com status atual |
GET |
/api/experiments/{experimentId}/containers/{containerName}/logs |
getContainerLogs |
Ultimas linhas de log de um container do projeto (docker logs --tail) |
GET |
/api/experiments/{experimentId}/mqtt-messages |
listMqttMessages |
Ultimas mensagens observadas no barramento MQTT para este experimento (aba de diagnostico) |
GET |
/api/experiments/{experimentId}/aggregation-config |
getAggregationConfig |
Retorna o identificador da estrategia de agregacao padrao do contrato |
POST |
/api/experiments/{experimentId}/sim-session/start |
startSimulationSession |
Inicia sessao de simulacao controlada pelo monitor |
GET |
/api/experiments/{experimentId}/sim-session |
getSimulationSession |
Consulta o estado da sessao de simulacao |
POST |
/api/experiments/{experimentId}/sim-session/send-round |
sendSimulationRound |
Envia a proxima rodada da sessao |
POST |
/api/experiments/{experimentId}/sim-session/run-all |
runAllSimulationRounds |
Executa as rodadas restantes da sessao em sequencia |
POST |
/api/experiments/{experimentId}/sim-session/pause |
pauseSimulationSession |
Pausa sessao de simulacao |
POST |
/api/experiments/{experimentId}/sim-session/resume |
resumeSimulationSession |
Retoma sessao pausada |
POST |
/api/experiments/{experimentId}/sim-session/stop |
stopSimulationSession |
Encerra sessao de simulacao |
GET |
/api/experiments/{experimentId}/simulation-config |
getSimulationConfig |
Retorna a configuracao de simulacao (fonte de dados, hiperparametros) do experimento |
POST |
/api/experiments/{experimentId}/simulation-config |
saveSimulationConfig |
Salva a configuracao de simulacao do experimento |
experiments¶
Contratos de experimentos federados (criacao, consulta, deploy, clone)
| Método | Caminho | operationId |
Resumo |
|---|---|---|---|
GET |
/api/experiments |
listExperiments |
Lista todos os experimentos registrados |
POST |
/api/experiments |
createExperiment |
Cria um contrato de experimento em DRAFT |
GET |
/api/experiments/{experimentId} |
getExperiment |
Detalhe JSON do experimento (contrato + consentimentos + rodadas) |
POST |
/api/experiments/{experimentId}/clone |
cloneExperiment |
Clona um experimento existente sob um novo experimentId (mesmo prefixo canonico) |
POST |
/api/experiments/deploy |
deployExperimentPackage |
Implanta um pacote de experimento .hdtpkg.zip |
POST |
/api/experiments/{experimentId}/update |
updateExperimentObjective |
Atualiza o objetivo de um contrato DRAFT |
POST |
/api/experiments/{experimentId}/delete |
undeployExperiment |
Remove o experimento dinamico implantado do monitor |
GET |
/api/experiments/{experimentId}/state |
getExperimentState |
Estado operacional canonico do experimento |
GET |
/api/experiments/{experimentId}/code |
getExperimentCode |
Metadados do codigo de treino registrado (hash, manifesto, entrypoint) |
client-packages¶
Pacotes DEX MDPL assinados e distribuidos separadamente para Android
| Método | Caminho | operationId |
Resumo |
|---|---|---|---|
POST |
/api/client-packages/deploy |
deployAndroidClientPackage |
Implanta um pacote Android MDPL .hdtclient.zip independente |
GET |
/api/experiments/{experimentId}/client-package |
downloadAndroidClientPackage |
Baixa pacote MDPL assinado da versao do contrato |
client-installations¶
Registro anonimo de instalacoes do app coletor
| Método | Caminho | operationId |
Resumo |
|---|---|---|---|
POST |
/api/client-installations |
registerAnonymousInstallation |
Registra uma instalacao pelo UUID anonimo gerado no aplicativo |
lifecycle¶
Transicoes de ciclo de vida do contrato (publish/activate/pause/...)
| Método | Caminho | operationId |
Resumo |
|---|---|---|---|
POST |
/api/experiments/{experimentId}/publish |
publishExperiment |
Publica o contrato e notifica participantes por MQTT |
POST |
/api/experiments/{experimentId}/activate |
activateExperiment |
Ativa um experimento publicado ou retoma um experimento pausado |
POST |
/api/experiments/{experimentId}/pause |
pauseExperiment |
Pausa um experimento ativo |
POST |
/api/experiments/{experimentId}/close |
closeExperiment |
Fecha um experimento |
POST |
/api/experiments/{experimentId}/revoke |
revokeExperiment |
Revoga um experimento |
POST |
/api/experiments/{experimentId}/reset-session |
resetExperimentSession |
Reinicia a sessao stateful sem remover o historico de rodadas |
POST |
/api/experiments/{experimentId}/restart |
restartExperiment |
Reinicia o experimento e limpa o historico de rodadas |
GET |
/api/experiments/{experimentId}/lifecycle |
getExperimentLifecycle |
Retorna o status do contrato e as acoes permitidas |
rounds¶
Execucao e consulta de rodadas federadas
| Método | Caminho | operationId |
Resumo |
|---|---|---|---|
POST |
/api/experiments/{experimentId}/start |
startExperiment |
Inicia uma rodada do experimento |
POST |
/api/experiments/{experimentId}/run-rounds |
runRounds |
Executa N rodadas federadas, sem transportar dados brutos |
GET |
/api/experiments/{experimentId}/rounds |
listRounds |
Lista todas as rodadas do experimento com metricas |
GET |
/api/experiments/{experimentId}/rounds/{roundId} |
getRound |
Consulta uma rodada especifica |
POST |
/api/experiments/{experimentId}/run-with-dataset |
runWithDataset |
Executa rodada(s) usando o pacote de dataset vinculado |
POST |
/api/experiments/{experimentId}/run-experiment |
runExperimentFlow |
Executa o fluxo completo de um experimento |
POST |
/api/experiments/{experimentId}/rounds/{roundId}/clients/{clientId}/artifacts |
uploadClientRoundArtifacts |
Armazena artefatos Base64 da atualizacao local |
POST |
/api/experiments/{experimentId}/rounds/{roundId}/aggregation-result |
reportAggregationResult |
Registra resultado de agregacao recebido de daemon compativel |
datasets¶
Pacotes de dados (.hdtsim.zip) implantados e vinculados a experimentos
| Método | Caminho | operationId |
Resumo |
|---|---|---|---|
POST |
/api/experiments/{experimentId}/run-with-dataset |
runWithDataset |
Executa rodada(s) usando o pacote de dataset vinculado |
GET |
/api/experiments/{experimentId}/dataset-package |
getDatasetPackageBinding |
Consulta pacote de dataset vinculado ao experimento |
POST |
/api/experiments/{experimentId}/dataset-package |
bindDatasetPackage |
Vincula pacote ja implantado ao experimento |
POST |
/api/experiments/{experimentId}/dataset-package/unbind |
unbindDatasetPackage |
Remove vinculo de pacote de dataset |
POST |
/api/experiments/{experimentId}/start-replay |
startDatasetReplay |
Inicia replay MQTT do pacote vinculado |
GET |
/api/experiments/{experimentId}/datasets |
listExperimentDatasets |
Lista pacotes de dataset implantados e vinculaveis a este experimento |
GET |
/api/datasets |
listDatasets |
Lista todos os pacotes de dataset implantados (visao global, todos os experimentos) |
POST |
/api/datasets/deploy |
deployDataset |
Implanta um pacote de dados .hdtsim.zip |
GET |
/api/datasets/{datasetPackageId} |
getDataset |
Detalhe de um pacote de dataset implantado |
POST |
/api/datasets/{datasetPackageId}/delete |
undeployDataset |
Remove um pacote de dataset implantado |
clients¶
Consentimento (LGPD) e status dos clientes federados, do lado do operador
| Método | Caminho | operationId |
Resumo |
|---|---|---|---|
GET |
/api/experiments/{experimentId}/discovered |
listDiscoveredClients |
Lista clientes descobertos via anuncio HTTP/MQTT, com status de descoberta |
GET |
/api/experiments/{experimentId}/clients |
listExperimentClients |
Lista consentimentos e contadores dos clientes do experimento |
POST |
/api/experiments/{experimentId}/clients/{clientId} |
applyClientAction |
Adiciona um cliente ou registra sua decisao de consentimento (action=add|accept|reject|register) |
POST |
/api/experiments/{experimentId}/clients/{clientId}/announce |
announceClient |
Registra anuncio de presenca de participante |
POST |
/api/experiments/{experimentId}/clients/{clientId}/consent |
submitClientConsent |
Registra decisao de consentimento do participante |
POST |
/api/experiments/{experimentId}/clients/{clientId}/cddl-status |
reportCddlStatus |
Registra heartbeat de coleta CDDL/CDAL |
GET |
/api/cddl-status |
listCddlStatus |
Lista heartbeats de todos os participantes e experimentos |
GET |
/api/experiments/{experimentId}/cddl-status |
listCddlStatusByExperiment |
Lista heartbeats dos participantes de um experimento |
Schemas Declarados¶
| Schema | Tipo | Campos principais |
|---|---|---|
HealthStatus |
object |
status, ledgerMode, fabric, fabricBlocker |
IntegrationStatus |
object |
mqtt, fabric |
ApiError |
object |
error, status, max |
StatusOk |
object |
status |
ExperimentCloneResult |
object |
status, sourceExperimentId, experimentId, contractVersion |
ClientAnnouncementResult |
object |
status, clientId, experimentId |
ClientConsentResult |
object |
status, clientId, experimentId, consent, error |
CddlStatus |
object |
experiment_id, client_id, active_sensors, observation_count, capture_active, updated_at (+1) |
ClientRoundArtifacts |
object |
update_base64, metrics_base64, profile_base64 |
StoredClientArtifacts |
object |
update_uri, update_hash, metrics_uri, metrics_hash, profile_uri, profile_hash |
AggregationResultRequest |
object |
report, updateNorms, localMetrics, clientUpdateHashes, clientUpdateVectors, localMetricName |
SimulationSession |
object |
experimentId, datasetType, datasetPath, maxClients, totalRounds, currentRound (+6) |
SimulationConfig |
object |
dataSourceMode, numRounds, epochs, learningRate, batchSize, fedProxMu (+9) |
StoppedSimulationSession |
object |
status, experimentId |
DatasetBinding |
object |
experimentId, datasetPackageId, descriptorExperimentId, divergentFromDescriptor |
UnboundDataset |
object |
status, experimentId |
ReplayStarted |
object |
status, experimentId, datasetPackageId, divergentFromDescriptor |
ExperimentSummary |
object |
experiment_id, contract_version, status, coordinator_id, rounds, accepted_clients |
ExperimentDetail |
object |
experiment_id, contract_version, status, coordinator_id, objective, task_type (+10) |
ClientConsent |
object |
client_id, status, timestamp, transaction_id |
ClientList |
object |
accepted_count, pending_count, rejected_or_revoked_count, items |
RoundMonitor |
object |
round_id, status, global_model_version, started_at, deadline, ended_at |
RoundMetrics |
object |
round_id, status, global_model_version, started_at, deadline, ended_at (+10) |
ExperimentState |
object |
api_version, generated_at, experiment, lifecycle, clients, rounds (+8) |
GlobalModel |
object |
model_version, model_hash, model_uri, transaction_id |
PerformancePoint |
object |
round_id, identifier, worker_id, performance, task_key |
AssetList |
object |
total, filters, assets |
CommandResult |
object |
status, experimentId, contractVersion, command, statusUrl, rounds_requested (+1) |
Explorador Interativo (Swagger UI)¶
Visualização interativa
O explorador abaixo carrega a biblioteca swagger-ui-dist no navegador. Em ambientes totalmente offline, utilize as tabelas acima ou baixe o arquivo YAML diretamente.