uxmEssentials-REST

What it does

uxmEssentials publishes a developer API that any plugin on the server can compile against. This add-on puts that same reach on a socket, so a program written in anything can use it.

• Read balances, homes, warps, player-warps, kits, vaults, sanctions and punishment history, playtime, AFK and vanish state, teleport requests, worlds, votes, mail and ignores.
• Write deposits, withdrawals and transfers; homes and warps; kit grants and claims; bans, mutes, kicks, warns and jails; god, flight, game mode, speed, heal and feed; teleports; world load and unload; votes and party progress; messages and mail.
• Subscribe to a live event stream over WebSocket, carrying every one of the seventy-four things uxmEssentials announces, so nothing has to be found out by polling.

It is built on the published API and nothing else. Every endpoint is one call to a surface a plugin could make itself, which is the rule that keeps the two from drifting apart.

Tokens, made in game

/uxmapi token create <label> [scopes]   issue one, shown once
/uxmapi token list                      what exists, without the secrets
/uxmapi token revoke <label>            stop one working
/uxmapi status                          whether it is listening, and who is connected

The secret is printed once, click-to-copy, and never again; what the server keeps is a hash. There is nowhere to paste a secret into a config file, because a secret in a config file ends up in a paste bin, a backup, and a support ticket.

Three scopes, granted per token: read for every GET, write for every POST, events for the stream. Both Authorization: Bearer and HTTP Basic work.

Setup

1. Drop uxmEssentials-rest-0.8.0.jar into plugins/ alongside the main uxmEssentials jar and restart.

2. Nothing opens. The add-on writes plugins/uxmEssentials-rest/config/rest.conf, says in the log where the switch is, and stays dormant, because a jar that starts listening because it was installed is an incident rather than a feature.

   enabled = false
   
   # Where to listen. The default is the loopback address, which is where this belongs.
   bind = "127.0.0.1"
   port = 8123
   
   # How many requests one token may make per minute.
   requests-per-minute = 120
   
   # How many event-stream connections may be open at once, across every token.
   max-subscribers = 8
   

3. Set enabled = true, restart, and issue a token with /uxmapi token create panel.

curl -H "Authorization: Bearer uxm_..." \
  http://127.0.0.1:8123/api/v1/players/$UUID/balance

{ "ok": true, "data": { "currency": "coins", "amount": 1250.50 } }

An operation the server understood and declined is not an HTTP error: it comes back with ok:false and the same failure code the Java API returns, so a consumer branches on the same string over HTTP as in process.

Requirements

• Server: Paper 26.2 running uxmEssentials 0.8.0.
• Main jar required this add-on does nothing on its own.
• No TLS. The listener speaks plain HTTP and defaults to the loopback address. Put a reverse proxy in front of it if the outside world needs to reach it.

Notes

Open source (GPL-3.0). Full endpoint, body-field and event reference: docs.uxplima.com.