Web-API [v4] - AdminPanel & RESTful web server [now with screenshots!]

Can’t wait :slight_smile: Best sponge plugin.

Excited too ! @tridaak why is your main goal with webapi ? Mine is empire management :slight_smile:

Would it be possible to add a plugin API in the future to expose data, such as if a player is jailed or muted? I can see plugins wanting to expose their own endpoints, it would be really nifty if you could add that!

That is certainly something very interesting and something I’ve thought about before. Although I’m not quite sure to what extent this API would be.

Currently it already is possible to specify serializers for custom classes, so other plugins could choose how to serialize their data (probably mostly events). But I was also thinking about complete endpoints for plugins (but that sounds like a lot of work for other plugins to implement) or something like automated endpoints where the plugins can just specify what kind of data to expose and the Web-API takes care of the rest (which in turn is more work for the Web-API)

I’m going to assume with jailed and muted you were referring to something Nucleus would do (love your plugin btw.)? Does it add extra data to the player object using the data serializers? It would certainly be interesting to query and display such data!

They were just examples, but yes, I’d consider writing a bridge plugin that would display that information if you had an API that gave plugins an endpoint. I don’t think you need to completely hold a plugin’s hand, but you certainly would need to develop a structure that would allow a plugin to say “I want to register this POST endpoint with these variables”.

As for my specific examples - I don’t add extra data to players, no, so that’s not an option, but I do add permission contexts (nucleus_jailed, nucleus_jail and nucleus_muted). I suppose that’s something that could be obtained through the API as it should be fairly standard - it’s part of the Permission API.

Anyway, if you do write an API that plugins can integrate with, that’d be neat. I understand why it’s potentially a lot of work though - just wondered what plans might be!

(Thanks for the kind words on Nucleus.)

Hi @Valandur!
I’m currently trying to develop a PHP API which answer your WEBAPI Plugin. The script is currently short but I’m having issue with it. The script is hosted by a NGINX server on a VM, and on my computer. I used whitelist permissions and added my IP and the NGINX server IP. But only the php script hosted on my computer can get player data (/api/player/{uuid} request. The script is exactly the same, and I’m pretty sure about my NGINX VM IP. In fact the script on VM get the answer “403 forbidden”. So I think it’s about perms, but I don’t understand why. Can you bring light on this obvious case ?

Thanks !

1 Like

Hey guys I made another huge update, so I thought it was time to take this to version 4 :smiley:
I am very happy to announce that the Web-API now has an admin panel to manage your server, with some very interesting features already available!

CAUTION, THIS IS A PRE-RELEASE, AND MAY BE UNSTABLE AND/OR CONTAIN BUGS. IT ALSO FEATURES ONLY VERY LIMITED DOCUMENTATION OF THE NEW ENDPOINTS, I WILL BE FOLLOWING UP WITH THIS AS SOON AS I CAN

To use the admin panel you need to create a user, which currently are saved in the users.conf config file (might be moved to a database later). The easiest way to create a user is to run the /webapi users add [name] [pw] command in your console. If you don’t specify a password the Web-API will generate a random one for you.
Then you can hit up localhost:8080/admin in your browser (or whatever URL your Web-API is available at) and play around with the new Admin Panel.

CAUTION WHEN USING THE ADMIN PANEL: THERE ARE NO CONFIRMATIONS YET, SO CLICKING DELETE ON A WORLD WILL DELETE IT WITHOUT ASKING. PLEASE BE CAREFUL WHEN USING THE PANEL, AND POSSIBLE CREATE A BACKUP OF THE IMPORTANT DATA OF YOUR SERVER FIRST.

I hope all of you have some time to play around with it and give me some feedback. Thank you very much for testing my plugin and keeping me going on this amazing trip of creating an awesome sponge plugin :smiley:


Below the official release notes from the Ore thread and GitHub:

A new version has been released for Web-API, it is available for download here.


  • Added an Admin-Panel to manage the server, available at /admin [WIP]
  • Improved lots of serializers
  • Add registry servlet to allow querying sponge registry (dimension types, entity types, etc.)
  • Allow creating/updating/deleting worlds with POST,PUT and DELETE requests
  • Fix various issues with worlds
  • Allow including details in list endpoints (with ?details)
  • Allow creating/modifying/deleting entities with POST,PUT and DELETE requests
  • Add ok boolean property to all endpoints
  • Add users that provide a username and password for temporary api keys
  • Fix executing void methods on objects returning an error
  • Fix inventory serialization

This is definitely a nginx issue, I solved mine by changing chmod. Otherwise, I use postman and logs for testing purposes.

@Valandur You wave me a lot of time, thanks for this admin panel !

A new version has been released for Web-API, it is available for download here.


  • Add first version of the Web-API API (it’s like PHP’s RecursiveIteratorIterator, API-ception)
  • Fix some servlets not returning “ok” property
  • Improve startup output log
  • Clean up swagger docs (internal)
  • Add all new routes to swagger docs
  • Add HTTPS support with custom keystore
  • Add commands to list all AdminPanel users and change their passwords
  • Update AdminPanel to 9b0ce54

  • Fix Web-API API not working
2 Likes

I have added a first version of an api to this release (Web-API API - :joy:) on github.
The basic usage would be along the lines of (I will be adding a more proper documentation later):

  1. Make a Class/Servlet (a class that handles certain routes with the same base) that implements IServlet
    (It doesn’t actually have any methods to implement, not yet at least)
    You can check out the servlets in the Web-API project to get an idea of how they work (e.g. Info Servlet)
  • The servlet class also needs to have the @WebAPIServlet annotation.

  • To create a route add a method to the servlet class that has one parameter of type IServletData (note the IServletData, not like in the example servlets linked above) and has the annotation @WebAPIRoute

  1. In your main plugin class (or wherever, not in the servlet above) using the WebAPIAPI class call the static method getServletService to get a reference to the servlet service. (Web-API registers itself in the GamePreInitializationEvent stage, so you probably can’t do it before that)

  2. With the ServletService use registerServlet(Class<? extends IServlet> servlet) to register your servlet (passing the class, not an instance) (The Web-API starts the Servlets in the GameStartedServerEvent stage, so you have to do it before that)

  3. Your servlet will be available at /api/{basePath} (you specified {basePath} in the @WebAPIServlet annotation)

I hope that explanation was good enough for anyone willing to try it. I will be working on a more proper documentation as soon as possible.

1 Like

A new version has been released for Web-API, it is available for download here.


  • Fix large block volumes causing memory exception without appropriate error messages (this does NOT increase your server memory)
  • Fix AdminPanel not working under some systems
  • Remove duplicate commands in command listing
  • Fix commands not being loaded on server start
  • Update to AdminPanel v0.2.1
    • Added autosuggest to command execution field

A new version has been released for Web-API, it is available for download here.


  • Add chunk and map endpoints
  • Rework block updates to be block operations, and also make block-volume-get operations async
  • Refactor serializers to not need JsonGenerator and SerializerProvider
  • Split cache definitions and implementation
  • Rename WebAPIRoute to WebAPIEndpoint
  • Clean up server stats
  • Update to AdminPanel v0.2.3 (Includes AdminPanel v0.2.2)
    • Add map page
    • Add block operations page
    • Add tps and player graph to dashboard
    • Fix page redirects not working properly

Hey guys, this is another big update for the Web-API. It adds the chunk & map endpoints (which allows showing a map in the admin panel, where one can easily see where entities, players and tile-entities are). I’ve also reworked all block operations to be async (including the get operations for more than one block). The admin panel also contains a graph on the dashboard with the TPS and player count, as well as a page for the reworked block operations.

I have added a bit of documentation for the Web-API API (still a work in progress, and currently only on the develop branch) which can be found here. I will update this with more information soon™.

Hope you all enjoy it :smiley:

2 Likes

Sounds amazing, can’t wait to try it out.

Wow, I have been busy for the past month but this V4 sounds awesome :smiley:

Please note that this new version of Web-API now uses bStats to track plugin usage.
It also contains sentry.io, which automatically reports errors. Error reports do NOT contain your server ip or any othe personal information.

Both these features can be turned off, bStats has it’s own config file and sentry can be turned off in the main config file config.conf by setting reportErrors = false

A new version has been released for Web-API, it is available for download here.


  • Add integrations for other plugins, so that they have endpoints and show up in the admin panel
    • Nucleus
    • HuskyCrates
  • Add documentation for Web-API API
  • Add endpoints for chunks
  • Update documentation for block operations
  • Add endpoint to show loaded servlets
  • Remove entities when they expire
  • Add “once” field to message so players can only reply once
  • Improve serialization of items & add damage cause serializer
  • Add bStats for statistics
  • Add Sentry for error logging
  • Remove parameters from hook URL and headers
  • Update to AdminPanel v0.3.1
    • Add integrations for other plugins
    • Use semantic-ui instead of react-strap (removes the need for jquery)
    • Add wait lines and wait time to command execution
    • Add Sentry for error logging
    • Add info messages to unfinished pages
2 Likes

I released a new version with a few bugfixes. Once some more testing has gone into this version i will make it a stable release. Thanks for everyone that is helping and reporting errors :smiley:

A new version has been released for Web-API, it is available for download here.


  • Various fixes and improvements for sentry error logging
  • Update docs to match endpoints
  • Add “ok” property to some endpoints that didn’t have it yet
  • Fix concurrency issues with server stats
  • Fix errors when requesting server properties
2 Likes

Thank you for your hard work, amazing how much the plugin has advanced in the past months, honestly my favorite sponge plugin.

Also, noticed the title says “Now with screenshots” but don’t see any images on the main post.

@tridaak Thank you very much :smiley:

There should be a title saying AdminPanel screenshots in the main post. There’s spoilers/arrows that you can click to show the screenshots. Sadly they are now slightly out of date, and the AdminPanel doesn’t look quite the same anymore, but it still works the same - it’s just the layout/style that changed.

A new version has been released for Web-API, it is available for download here.


  • Add more information to Sentry log messages and fix some issues
  • Fix cached commands throwing errors when reloading
  • Move default HTTPS port to 8081, and warn when a port is below 1024
1 Like