Skip to content

Latest commit

 

History

History
509 lines (447 loc) · 33.2 KB

README.md

File metadata and controls

509 lines (447 loc) · 33.2 KB
Raw

Web-API - Java Client

Access Sponge powered Minecraft servers through a WebAPI

Introduction

This is the documentation of the various API routes offered by the WebAPI plugin.
This documentation assumes that you are familiar with the basic concepts of Web API's, such as GET, PUT, POST and DELETE methods, request HEADERS and RESPONSE CODES and JSON data.
By default this documentation can be found at http:/localhost:8080 (while your minecraft server is running) and the various routes start with http:/localhost:8080/api/v5...
As a quick test try reaching the route http:/localhost:8080/api/v5/info (remember that you can only access \"localhost\" routes on the server on which you are running minecraft). This route should show you basic information about your server, like the motd and player count.

List endpoints

Lots of objects offer an endpoint to list all objects (e.g. GET: /world to get all worlds). These endpoints return only the properties marked 'required' by default, because the list might be quite large. If you want to return ALL data for a list endpoint add the query parameter details, (e.g. GET: /world?details).

Remember that in this case the data returned by the endpoint might be quite large.

Debugging endpoints

Apart from the ?details flag you can also pass some other flags for debugging purposes. Remember that you must include the first query parameter with ?, and further ones with &:

  • details: Includes details for list endpoints
  • accept=[json/xml]: Manually set the accept content type. This is good for browser testing, BUT DON'T USE THIS IN PRODUCTION, YOU CAN SUPPLY THE Accepts HEADER FOR THAT
  • pretty: Pretty prints the data, also good for debugging in the browser.

An example request might look like this: http://localhost:8080/api/v5/world?details&accpet=json&pretty&key=MY-API-KEY

Additional data

Certain endpoints (such as /player, /entity and /tile-entity have additional properties which are not documented here, because the data depends on the concrete object type (eg. Sheep have a wool color, others do not) and on the other plugins/mods that are running on your server which might add additional data.
You can also find more information in the github docs (https:/github.com/Valandur/Web-API/tree/master/docs/DATA.md)

Swagger

Web-API

  • API version: 5.4.2-S7.1.0
    • Build date: 2019-07-23T13:32:53.543+02:00

Automatically generated by the Swagger Codegen

Requirements

Building the API client library requires:

  1. Java 1.7+
  2. Maven/Gradle

Installation

To install the API client library to your local Maven repository, simply execute:

mvn clean install

To deploy it to a remote Maven repository instead, configure the settings of the repository and execute:

mvn clean deploy

Refer to the OSSRH Guide for more information.

Maven users

Add this dependency to your project's POM:

<dependency>
  <groupId>io.swagger</groupId>
  <artifactId>swagger-java-client</artifactId>
  <version>1.0.0</version>
  <scope>compile</scope>
</dependency>

Gradle users

Add this dependency to your project's build file:

compile "io.swagger:swagger-java-client:1.0.0"

Others

At first generate the JAR by executing:

mvn clean package

Then manually install the following JARs:

  • target/swagger-java-client-1.0.0.jar
  • target/lib/*.jar

Getting Started

Please follow the installation instruction and execute the following Java code:

import io.swagger.client.*;
import io.swagger.client.auth.*;
import io.swagger.client.model.*;
import io.swagger.client.api.ActiveTimeApi;

import java.io.File;
import java.util.*;

public class ActiveTimeApiExample {

    public static void main(String[] args) {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        
        // Configure API key authorization: ApiKeyHeader
        ApiKeyAuth ApiKeyHeader = (ApiKeyAuth) defaultClient.getAuthentication("ApiKeyHeader");
        ApiKeyHeader.setApiKey("YOUR API KEY");
        // Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null)
        //ApiKeyHeader.setApiKeyPrefix("Token");

        // Configure API key authorization: ApiKeyQuery
        ApiKeyAuth ApiKeyQuery = (ApiKeyAuth) defaultClient.getAuthentication("ApiKeyQuery");
        ApiKeyQuery.setApiKey("YOUR API KEY");
        // Uncomment the following line to set a prefix for the API key, e.g. "Token" (defaults to null)
        //ApiKeyQuery.setApiKeyPrefix("Token");

        ActiveTimeApi apiInstance = new ActiveTimeApi();
        Boolean details = true; // Boolean | Add to include additional details, omit or false otherwise
        String accept = "accept_example"; // String | Override the 'Accept' request header (useful for debugging your requests)
        Boolean pretty = true; // Boolean | Add to make the Web-API pretty print the response (useful for debugging your requests)
        try {
            ServerReport result = apiInstance.getServerReport(details, accept, pretty);
            System.out.println(result);
        } catch (ApiException e) {
            System.err.println("Exception when calling ActiveTimeApi#getServerReport");
            e.printStackTrace();
        }
    }
}

Documentation for API Endpoints

All URIs are relative to https://localhost/api/v5

Class Method HTTP request Description
ActiveTimeApi getServerReport GET /active-time Server report
ActiveTimeApi getUserReport GET /active-time/user/{uuid} User report
BlockApi createBlockOperation POST /block/op Create a block operation
BlockApi deleteBlockOperation DELETE /block/op/{uuid} Stop a block operation
BlockApi getBlock GET /block/{world}/{x}/{y}/{z} Get a block
BlockApi getBlockOperation GET /block/op/{uuid} Get a block operation
BlockApi listBlockOperations GET /block/op List block operations
BlockApi modifyBlockOperation PUT /block/op/{uuid} Modify a block operation
ChunkApi createChunkAt POST /chunk/{world}/{x}/{z} Load & Generate a chunk
ChunkApi getChunkAt GET /chunk/{world}/{x}/{z} Get a chunk
ChunkApi listChunks GET /chunk/{world} List chunks
CmdSchedulerApi deleteTask DELETE /cmd-scheduler/{name} Delete a task
CmdSchedulerApi listTasks GET /cmd-scheduler List tasks
CommandApi getCommand GET /cmd/{cmd} Get a command
CommandApi listCommands GET /cmd List commands
CommandApi runCommands POST /cmd Execute a command
EconomyApi getAccount GET /economy/account/{id} List currencies
EconomyApi getCurrencies GET /economy/currency List currencies
EntityApi createEntity POST /entity Spawn an entity
EntityApi executeMethod POST /entity/{entity}/method Execute a method
EntityApi getEntity GET /entity/{entity} Get entity
EntityApi listEntities GET /entity List entities
EntityApi modifyEntity PUT /entity/{entity} Modify an entity
EntityApi removeEntity DELETE /entity/{entity} Destroy an entity
HistoryApi getChat GET /history/message Get message history
HistoryApi getCommands GET /history/cmd Get command history
InfoApi getInfo GET /info Server info
InfoApi getStats GET /info/stats Server stats
InfoApi listServlets GET /info/servlets List servlets
InteractiveMessageApi getMessage GET /interactive-message/{uuid} Get a message
InteractiveMessageApi listMessages GET /interactive-message List messages
InteractiveMessageApi sendMessage POST /interactive-message Send a message
InventoryApi addElement POST /megamenus/menu/{mid}/{page}/{y}/{x} Add element
InventoryApi closeRenderer DELETE /megamenus/render/{mid}/{viewer} Close renderer
InventoryApi createMenu POST /megamenus/menu Create menu
InventoryApi createRenderer POST /megamenus/render/{mid} Create menu
InventoryApi deleteElement DELETE /megamenus/menu/{mid}/{page}/{y}/{x} Delete menu
InventoryApi deleteMenu DELETE /megamenus/menu/{mid} Delete menu
InventoryApi deletePage DELETE /megamenus/menu/{mid}/{page} Delete a page of elements
InventoryApi deleteRenderer DELETE /megamenus/renderer/{mid} Delete menu
InventoryApi findRenderer GET /megamenus/render/find/{viewer} Get the renderer for viewer
InventoryApi getElement GET /megamenus/menu/{mid}/{page}/{y}/{x} Get menu
InventoryApi getMenu GET /megamenus/menu/{mid} Get menu
InventoryApi getPage GET /megamenus/menu/{mid}/{page} Reads a single page of elements
InventoryApi getRenderer GET /megamenus/render/{mid} Get the renderer for this menu
InventoryApi listMenus GET /megamenus/menu List menus
InventoryApi listRenderer GET /megamenus/render List renderer
InventoryApi openRenderer PUT /megamenus/render/{mid}/{viewer} Open renderer
InventoryApi setElement PUT /megamenus/menu/{mid}/{page}/{y}/{x} Update menu
InventoryApi setMenu PUT /megamenus/menu/{mid} Update menu
MapApi getMap GET /map/{world}/{x}/{z} Get a map tile
MegaMenusApi addElement POST /megamenus/menu/{mid}/{page}/{y}/{x} Add element
MegaMenusApi closeRenderer DELETE /megamenus/render/{mid}/{viewer} Close renderer
MegaMenusApi createMenu POST /megamenus/menu Create menu
MegaMenusApi createRenderer POST /megamenus/render/{mid} Create menu
MegaMenusApi deleteElement DELETE /megamenus/menu/{mid}/{page}/{y}/{x} Delete menu
MegaMenusApi deleteMenu DELETE /megamenus/menu/{mid} Delete menu
MegaMenusApi deletePage DELETE /megamenus/menu/{mid}/{page} Delete a page of elements
MegaMenusApi deleteRenderer DELETE /megamenus/renderer/{mid} Delete menu
MegaMenusApi findRenderer GET /megamenus/render/find/{viewer} Get the renderer for viewer
MegaMenusApi getElement GET /megamenus/menu/{mid}/{page}/{y}/{x} Get menu
MegaMenusApi getMenu GET /megamenus/menu/{mid} Get menu
MegaMenusApi getPage GET /megamenus/menu/{mid}/{page} Reads a single page of elements
MegaMenusApi getRenderer GET /megamenus/render/{mid} Get the renderer for this menu
MegaMenusApi listMenus GET /megamenus/menu List menus
MegaMenusApi listRenderer GET /megamenus/render List renderer
MegaMenusApi openRenderer PUT /megamenus/render/{mid}/{viewer} Open renderer
MegaMenusApi setElement PUT /megamenus/menu/{mid}/{page}/{y}/{x} Update menu
MegaMenusApi setMenu PUT /megamenus/menu/{mid} Update menu
MenuApi addElement POST /megamenus/menu/{mid}/{page}/{y}/{x} Add element
MenuApi closeRenderer DELETE /megamenus/render/{mid}/{viewer} Close renderer
MenuApi createMenu POST /megamenus/menu Create menu
MenuApi createRenderer POST /megamenus/render/{mid} Create menu
MenuApi deleteElement DELETE /megamenus/menu/{mid}/{page}/{y}/{x} Delete menu
MenuApi deleteMenu DELETE /megamenus/menu/{mid} Delete menu
MenuApi deletePage DELETE /megamenus/menu/{mid}/{page} Delete a page of elements
MenuApi deleteRenderer DELETE /megamenus/renderer/{mid} Delete menu
MenuApi findRenderer GET /megamenus/render/find/{viewer} Get the renderer for viewer
MenuApi getElement GET /megamenus/menu/{mid}/{page}/{y}/{x} Get menu
MenuApi getMenu GET /megamenus/menu/{mid} Get menu
MenuApi getPage GET /megamenus/menu/{mid}/{page} Reads a single page of elements
MenuApi getRenderer GET /megamenus/render/{mid} Get the renderer for this menu
MenuApi listMenus GET /megamenus/menu List menus
MenuApi listRenderer GET /megamenus/render List renderer
MenuApi openRenderer PUT /megamenus/render/{mid}/{viewer} Open renderer
MenuApi setElement PUT /megamenus/menu/{mid}/{page}/{y}/{x} Update menu
MenuApi setMenu PUT /megamenus/menu/{mid} Update menu
PermissionApi getCollection GET /permission/collection/{id} Get collection
PermissionApi getSubject GET /permission/collection/{id}/subject/{subId} Get subject
PermissionApi listCollections GET /permission/collection List collections
PermissionApi listSubjects GET /permission/collection/{id}/subject List subjects
PlayerApi executeMethod POST /player/{player}/method Execute a method
PlayerApi getPlayer GET /player/{player} Get a player
PlayerApi listPlayers GET /player List players
PlayerApi modifyPlayer PUT /player/{player} Modify a player
PluginApi changePluginConfig POST /plugin/{plugin}/config Change plugin configs
PluginApi getPlugin GET /plugin/{plugin} Get a plugin
PluginApi getPluginConfig GET /plugin/{plugin}/config Get plugin configs
PluginApi listPlugins GET /plugin List plugins
PluginApi togglePlugin PUT /plugin/{plugin} Toggle a plugin
RecipeApi listRecipes GET /recipe List recipes
RedProtectApi createRegion POST /red-protect/region Create a region
RedProtectApi deleteRegion DELETE /red-protect/region/{id} Delete a region
RedProtectApi getRegion GET /red-protect/region/{id} Get a region
RedProtectApi listRegions GET /red-protect/region List regions
RedProtectApi modifyRegion PUT /red-protect/region/{id} Modify a region
RegistryApi getRegistry GET /registry/{class} Get a catalog type
ServerApi listProperties GET /server/properties List server properties
ServerApi modifyProperties PUT /server/properties Modify server properties
TileEntityApi executeMethod POST /tile-entity/{world}/{x}/{y}/{z}/method Execute a method
TileEntityApi getTileEntity GET /tile-entity/{world}/{x}/{y}/{z} Get tile entity
TileEntityApi listTileEntities GET /tile-entity List tile entities
TileEntityApi modifyTileEntity PUT /tile-entity/{world}/{x}/{y}/{z} Modify tile entity
UiApi addElement POST /megamenus/menu/{mid}/{page}/{y}/{x} Add element
UiApi closeRenderer DELETE /megamenus/render/{mid}/{viewer} Close renderer
UiApi createMenu POST /megamenus/menu Create menu
UiApi createRenderer POST /megamenus/render/{mid} Create menu
UiApi deleteElement DELETE /megamenus/menu/{mid}/{page}/{y}/{x} Delete menu
UiApi deleteMenu DELETE /megamenus/menu/{mid} Delete menu
UiApi deletePage DELETE /megamenus/menu/{mid}/{page} Delete a page of elements
UiApi deleteRenderer DELETE /megamenus/renderer/{mid} Delete menu
UiApi findRenderer GET /megamenus/render/find/{viewer} Get the renderer for viewer
UiApi getElement GET /megamenus/menu/{mid}/{page}/{y}/{x} Get menu
UiApi getMenu GET /megamenus/menu/{mid} Get menu
UiApi getPage GET /megamenus/menu/{mid}/{page} Reads a single page of elements
UiApi getRenderer GET /megamenus/render/{mid} Get the renderer for this menu
UiApi listMenus GET /megamenus/menu List menus
UiApi listRenderer GET /megamenus/render List renderer
UiApi openRenderer PUT /megamenus/render/{mid}/{viewer} Open renderer
UiApi setElement PUT /megamenus/menu/{mid}/{page}/{y}/{x} Update menu
UiApi setMenu PUT /megamenus/menu/{mid} Update menu
UniversalMarketApi listMarketItems GET /universal-market/item List items
UserApi createUser POST /user Create a user
UserApi deleteUser DELETE /user/{name} Delete a user
UserApi getMe GET /user/me Check info
UserApi getUsers GET /user List users
UserApi login POST /user/login Login
UserApi logout POST /user/logout Logout
UserApi logoutRedirect GET /user/logout
UserApi modifyUser PUT /user/{name} Update a user
VShopsApi addShopItem POST /vshop/shop/{id}/item Add Shop Item
VShopsApi createShop POST /vshop/shop Create Shops
VShopsApi deleteShop DELETE /vshop/shop/{id} Delete a Shop
VShopsApi deleteShopItem DELETE /vshop/shop/{id}/item/{item} Removes a Shop Item
VShopsApi getShop GET /vshop/shop/{id} Get a Shop
VShopsApi getShopItem GET /vshop/shop/{id}/item/{item} Get a Shop
VShopsApi listShopItems GET /vshop/shop/{id}/item List Shop Items
VShopsApi listShops GET /vshop/shop List Shops
VShopsApi updateShop PUT /vshop/shop/{id} Change Shop
VShopsApi updateShopItem PUT /vshop/shop/{id}/item/{item} Change Shop Item
VillagerShopsApi addShopItem POST /vshop/shop/{id}/item Add Shop Item
VillagerShopsApi addShopItem_0 POST /vshop/shop/{id}/item Add Shop Item
VillagerShopsApi createShop POST /vshop/shop Create Shops
VillagerShopsApi createShop_0 POST /vshop/shop Create Shops
VillagerShopsApi deleteShop DELETE /vshop/shop/{id} Delete a Shop
VillagerShopsApi deleteShopItem DELETE /vshop/shop/{id}/item/{item} Removes a Shop Item
VillagerShopsApi deleteShopItem_0 DELETE /vshop/shop/{id}/item/{item} Removes a Shop Item
VillagerShopsApi deleteShop_0 DELETE /vshop/shop/{id} Delete a Shop
VillagerShopsApi getShop GET /vshop/shop/{id} Get a Shop
VillagerShopsApi getShopItem GET /vshop/shop/{id}/item/{item} Get a Shop
VillagerShopsApi getShopItem_0 GET /vshop/shop/{id}/item/{item} Get a Shop
VillagerShopsApi getShop_0 GET /vshop/shop/{id} Get a Shop
VillagerShopsApi listShopItems GET /vshop/shop/{id}/item List Shop Items
VillagerShopsApi listShopItems_0 GET /vshop/shop/{id}/item List Shop Items
VillagerShopsApi listShops GET /vshop/shop List Shops
VillagerShopsApi listShops_0 GET /vshop/shop List Shops
VillagerShopsApi updateShop PUT /vshop/shop/{id} Change Shop
VillagerShopsApi updateShopItem PUT /vshop/shop/{id}/item/{item} Change Shop Item
VillagerShopsApi updateShopItem_0 PUT /vshop/shop/{id}/item/{item} Change Shop Item
VillagerShopsApi updateShop_0 PUT /vshop/shop/{id} Change Shop
WebBooksApi createWebBook POST /web-books/book Create a book
WebBooksApi deleteWebBook DELETE /web-books/book/{id} Delete a book
WebBooksApi getWebBook GET /web-books/book/{id} Get a book
WebBooksApi getWebBookContent GET /web-books/book/{id}/html Book HTML
WebBooksApi getWebBookContentPost POST /web-books/book/{id}/html Book HTML
WebBooksApi listWebBooks GET /web-books/book List books
WebBooksApi modifyWebBook PUT /web-books/book/{id} Modify a book
WorldApi createWorld POST /world Create a world
WorldApi deleteWorld DELETE /world/{world} Delete a world
WorldApi executeMethod POST /world/{world}/method Execute a method
WorldApi getWorld GET /world/{world} Get a world
WorldApi listWorlds GET /world List worlds
WorldApi modifyWorld PUT /world/{world} Modify a world

Documentation for Models

Documentation for Authorization

Authentication schemes defined for the API:

ApiKeyHeader

  • Type: API key
  • API key parameter name: X-WebAPI-Key
  • Location: HTTP header

ApiKeyQuery

  • Type: API key
  • API key parameter name: key
  • Location: URL query string

Recommendation

It's recommended to create an instance of ApiClient per thread in a multithreaded environment to avoid any potential issues.

Author

inithilian@gmail.com