Purifier

A RESTful API Endpoint Plugin for Bukkit/Spigot API Server

Features

REST API

Access server resource by web request. no need to use buggy rcon

JWT Authorization

Make control for api access. you can set access accounts in config.yml. make sure you change "secret" before run server.

Local Cached Username-UUID lookup

The mojang api have hard limit for call. use cached user data for less mojang api call. *only works for joined player before

Auto-generated Swagger API Docs

Stop to handwriting api documents. It makes more free time for developers. you can find easy for spec and correct request. we recommended use the postman for develop.

Usage

Create JWT Token

1. make sure postman or test method have imported api url.
2. POST request to {baseUrl}/auth with { "username": :username, "password": :password }.
   • if you want more secure for authentication, use https request with proxy server.
   • do not expose purifier server alone. It may cause of security issue.
3. grab { "token": :token } for future access.

Username-UUID lookup

1. make sure postman or test method have imported api url.
2. request to {baseUrl}/api/v1/mojang-users/:username.
   • if you enabled authentication method, create bearer token and send with "Authorization: Bearer {token}" header.
3. this api response makes mojang-format compatible. you can grab same as mojang api like { "id": :uuid, "name": :username }.
   • if requested user is not exist, it return NO_CONTENT_204 status code same as mojang api.
4. it's only response for joined players. for "real existed all mojang users", use mojang api as failsafe in your application.

REST API

1. make sure postman or test method have imported api url.
2. follow api-docs for access.
3. if there is bug or something weird. make issue or pull request here.

API Access permissions examples

see latest code for check api access permission.

• ANON
  • it can access for anyone.
  • /health - check if server alive.
• READ
  • access for read permission user only.
  • this api only do read stuff.
  • /worlds/current-time - show current time in worlds.
• WRITE
  • access for read/write permission user only.
  • this api do read/write stuff for non-critical things.
  • /worlds/:world/storm - toggle storm for target world.
• ADMIN
  • access for admin permission user only.
  • this api do critical stuff.
  • all /server api.
    • it contains broadcast, reload and shutdown

Known Issues

• Functions not supported
  • Whitelist function
    • The original minecraft api has bug(MC-162683)
  • Ban function
    • This plugin based on kotlin. It can't support for named arguments for non-Kotlin functions.
    • We can't use minecraftServer.getBanList(BanList.Type.NAME).addBan()

Quick Start

1. Run $ gradlew shadowJar
2. Put purifier-${version}-SNAPSHOT-all.jar to your Bukkit/Spigot/Paper Server's plugins directory
   • It located in build/libs
   • or just download latest release.
3. Explore with OpenAPIv3 Supported Tools (like Postman)
   • You can access in http://localhost:8080/api-docs