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 [scopes] issue one, shown once /uxmapi token list what exists, without the secrets /uxmapi token revoke 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.7.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. ```hocon 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`. ```bash curl -H "Authorization: Bearer uxm_..." \ http://127.0.0.1:8123/api/v1/players/$UUID/balance ``` ```json { "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.1.2** running uxmEssentials **0.7.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](https://docs.uxplima.com/minecraft/uxmessentials/developer/rest-api/).