Ir para o conteúdo

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.