第三方站點串接Third-party stations

Other plugins can plug their own data into ServerAPI and have it served alongside the built-in endpoints, at /api/v1/custom/<name>. But whether it opens, and whether it needs a key, is entirely your call — a plugin can only ask; it cannot make its data public by itself.

For plugin developers

ServerAPI puts the registration entry point into Bukkit's ServicesManager when it enables. Grab it in your plugin's onEnable(). The minimum is two things: a station name and a function that returns the data.

var rsp = getServer().getServicesManager().getRegistration(ServerApiRegistry.class);
if (rsp == null) return;                 // No ServerAPI installed — just skip it
ServerApiRegistry api = rsp.getProvider();

api.register(CustomStation.builder("myplugin_stats", this)
        .supplier(() -> Map.of("kills", killCount, "wins", winCount))
        .build());

That is all. Once the owner enables it, the data shows up at /api/v1/custom/myplugin_stats, and the Map you return becomes JSON automatically.

Exposing player or world data?

With the code above, your function runs on the HTTP request thread, and that thread must not touch Bukkit — players, worlds and entities are only safe to read on the main thread. If that is exactly the kind of data you want to expose, add one line, .cached(seconds): ServerAPI then calls your function on the main thread every few seconds, stores the result, and serves that snapshot to readers.

api.register(CustomStation.builder("arena", this)
        .cached(5)                       // grab it on the main thread every 5s
        .supplier(() -> {
            World w = Bukkit.getWorld("arena");
            return Map.of("players", w.getPlayers().size(), "time", w.getTime());
        })
        .build());

In one line: if the data is already in memory and cheap to build, add nothing (live is the default); add .cached(seconds) only when you need player / world / entity data. That number is just a suggestion — the owner can change it.

A full example

A small plugin that does nothing but this looks about like:

public class MyPlugin extends JavaPlugin {

    private int kills = 0;
    private final UUID matchId = UUID.randomUUID();

    @Override
    public void onEnable() {
        var rsp = getServer().getServicesManager().getRegistration(ServerApiRegistry.class);
        if (rsp == null) {
            getLogger().info("No ServerAPI, skipping data integration.");
            return;
        }
        rsp.getProvider().register(CustomStation.builder("myplugin_stats", this)
                .description("My plugin stats")   // optional, shown in the /api/v1 index
                .supplier(this::snapshot)
                .build());
    }

    // Any of these types can be returned directly; ServerAPI converts to JSON recursively.
    // Use a LinkedHashMap if you need a null value, since Map.of rejects null.
    private Map<String, Object> snapshot() {
        Map<String, Object> data = new LinkedHashMap<>();
        data.put("kills", kills);                             // number (int)
        data.put("kdr", 2.4);                                 // number (double)
        data.put("ranked", true);                             // boolean
        data.put("topPlayer", "Alice");                       // string
        data.put("recentPlayers", List.of("Alice", "Bob"));   // array (List)
        data.put("lastScores", new int[]{10, 8, 5});          // array (int[] works too)
        data.put("arena", Map.of("name", "sky", "round", 3)); // nested object (Map)
        data.put("matchId", matchId);                         // other types (UUID) become a string
        data.put("nextEvent", null);                          // null
        return data;
    }

    @Override
    public void onDisable() {
        var rsp = getServer().getServicesManager().getRegistration(ServerApiRegistry.class);
        if (rsp != null) rsp.getProvider().unregister("myplugin_stats");
    }
}

As above, the return value can be a Map, List, array, number, boolean, string or null, and any other type becomes a string. All plain Java. unregister stops serving but keeps the owner's config file, so nothing has to be reconfigured next time.

For how to add ServerAPI to your project and the full API reference, see Developer API. For a longer walkthrough and FAQ, see the integration guide.

For the owner: what you see

The moment a plugin asks, the console tells you and a config file appears — one file per station, named after the station:

# plugins/ServerAPI/custom/myplugin_stats.yml
# A plugin asked to expose its data through ServerAPI, so this file was created for it.
# It starts off: once you are happy with it, set enabled to true and run /serverapi reload.
plugin: CoolPlugin
path: /api/v1/custom/myplugin_stats
mode: async
registered-at: 2026-07-23T10:00:00

enabled: false           # false = the URL is closed (404); set true to actually serve it
require-key: true        # true = an API key is required; false = anyone can read it
protected-fields: []     # fields hidden from callers without a key, e.g. [balance]; [] shows all

To turn it on: set enabled to true and run /serverapi reload. Once enabled the station shows up in the /api/v1 index and obeys your existing three layers of access control (key, hidden fields, 404 for unauthorised requests), exactly like the built-in endpoints.

A cached station's file has one extra line, snapshot-seconds, controlling how often it refreshes; an async station reads live and has no such line.