
High-throughput server plugin & REST API bridge for Minecraft.
NoxAeApi-Velocity
A non-blocking network hub for multi-server Minecraft networks. Built for Velocity — bridges WebSocket node registry and REST API for NoxAeApi (Paper/Bukkit) backends.
What is NoxAeApi-Velocity?
NoxAeApi-Velocity is the proxy-side network hub for the NoxAeApi ecosystem. It runs a WebSocket registration server and a REST API inside Velocity, on its own Javalin/Jetty threads, so every connected backend (Paper) node pushes its state instead of dashboards and bots polling each server individually over REST.
It replaces the legacy REST-polling model in NoxAeApi-main with a persistent WS connection per node, giving consumers (dashboard, Alya Bot) instant, in-memory network status instead of stale, fanned-out HTTP calls.
- Push, not poll: backend nodes register and heartbeat over WebSocket at
/network/register; a watchdog marks a node offline the moment its heartbeat lapses, not on the next poll cycle. - Unified REST surface: a single
/v1API on the proxy aggregates status, player lookups and broadcast across the whole network — no more per-server endpoints to fan out to. - Live, not proxied: player and status endpoints read straight from Velocity's own
ProxyServerand the in-memory node registry, not a forwarded call to each backend. - Reload without a restart:
/noxaeapi reloadhot-reloadsnetwork-hub.ymland restarts the WS/REST servers and heartbeat watchdog, keeping connected node state intact. - Secure: per-node auth keys for WS registration, a separate API key for the REST surface.
Configuration
All configuration lives in network-hub.yml, generated in the plugin's data folder on first run:
network-hub:
enabled: true
ws-listen-port: 5000
# Keys backend servers must present when registering (checked against each
# backend's proxy-registration.proxy-key). Multiple entries let you rotate keys
# or use a different one per environment.
auth-keys:
- "proxy_secret_change_me"
# A node that hasn't sent a heartbeat within this window is marked offline, even
# if its WebSocket connection hasn't formally closed.
heartbeat-timeout-seconds: 30
# Backends this proxy can forward REST calls to via /v1/network/{id}/*.
servers:
- id: survival
label: "Survival"
url: "http://10.0.0.2:4567"
key: "proxy_secret_change_me"
- id: skyblock
label: "Skyblock"
url: "http://10.0.0.3:4567"
key: "proxy_secret_change_me"
# REST API exposed to outside consumers (dashboard, Alya Bot). Auth is a single
# key sent via the 'key' header.
api:
port: 4568
key: "dashboard_secret_change_me"
Commands
| Command | Permission | Description |
|---|---|---|
/noxaeapi reload |
noxaeapi.reload |
Reloads network-hub.yml and restarts the WS/REST servers and heartbeat watchdog without a full proxy restart. Connected node state is preserved. |
Documentation
Installation, configuration, the full API reference and SDK bindings are all at noxapi.noxlydev.xyz.
Support
- Bugs and feature requests: GitHub Issues
- Community: discord.gg/noxae
- Sponsor: GitHub Sponsors
© NoxlyDev. All rights reserved. NoxAeApi-Velocity is 100% closed-source, proprietary software.
