Getting started

The dependency

The API module depends on paper-api and nothing else, so you inherit no dependency graph from us.

repositories {
    maven("https://jitpack.io")
}

dependencies {
    compileOnly("com.github.Zephrynis.ZyAuctions:zyauctions-api:1.0.0")
}

compileOnly / provided, never implementation. The API classes are bundled inside the ZyAuctions jar and must resolve to the running plugin's copy. Shading them into yours will give you two versions of every interface and a ClassCastException the first time you touch one.

The manifest entry

plugin.yml

softdepend: [ZyAuctions]

Use softdepend if your plugin works without ZyAuctions, and depend if it does not. softdepend also guarantees ZyAuctions has finished enabling before yours does, which is what you want either way.

Getting the API

Bukkit's ServicesManager is the source of truth:

import com.zephrynis.zyauctions.api.ZyAuctionsApi;
import org.bukkit.plugin.RegisteredServiceProvider;

RegisteredServiceProvider<ZyAuctionsApi> rsp =
        getServer().getServicesManager().getRegistration(ZyAuctionsApi.class);
if (rsp == null) {
    getSLF4JLogger().info("ZyAuctions not found; auction features disabled.");
    return;
}
ZyAuctionsApi auctions = rsp.getProvider();

Or the convenience wrapper, which does the same lookup:

import com.zephrynis.zyauctions.api.ZyAuctions;

if (!ZyAuctions.available()) return;
ZyAuctionsApi auctions = ZyAuctions.get();

Do not cache the result across a plugin reload. The lookup is a map read; call it when you need it.

A complete plugin

This compiles as-is. It adds /cheapest <material>, which finds the cheapest active listing of a material and tells the player who is selling it.

CheapestPlugin.java

package com.example.cheapest;

import com.zephrynis.zyauctions.api.ZyAuctions;
import com.zephrynis.zyauctions.api.ZyAuctionsApi;
import com.zephrynis.zyauctions.api.model.Listing;
import com.zephrynis.zyauctions.api.model.ListingQuery;
import com.zephrynis.zyauctions.api.model.SortOrder;
import java.util.List;
import java.util.Locale;
import net.kyori.adventure.text.Component;
import org.bukkit.command.Command;
import org.bukkit.command.CommandSender;
import org.bukkit.plugin.java.JavaPlugin;

public final class CheapestPlugin extends JavaPlugin {

    @Override
    public boolean onCommand(
            CommandSender sender, Command command, String label, String[] args) {

        if (!ZyAuctions.available()) {
            sender.sendMessage(Component.text("The auction house isn't running."));
            return true;
        }
        if (args.length != 1) {
            sender.sendMessage(Component.text("Usage: /cheapest <material>"));
            return true;
        }

        ZyAuctionsApi auctions = ZyAuctions.get();
        List<Listing> matches = auctions.listings(ListingQuery.builder()
                .search(args[0].toLowerCase(Locale.ROOT))
                .sort(SortOrder.PRICE_LOW)
                .build());

        if (matches.isEmpty()) {
            sender.sendMessage(Component.text("Nothing like that is for sale."));
            return true;
        }

        Listing cheapest = matches.getFirst();
        sender.sendMessage(Component.text(
                cheapest.sellerName() + " is selling "
                        + cheapest.item().getAmount() + "x "
                        + cheapest.item().getType().name()
                        + " for " + cheapest.price()));
        return true;
    }
}

plugin.yml

name: Cheapest
version: 1.0.0
main: com.example.cheapest.CheapestPlugin
api-version: '26.2'
softdepend: [ZyAuctions]
commands:
  cheapest:
    usage: /cheapest <material>

Threading, in one paragraph

Reads — listing, listings, listingsOf, collectibles, activeListingCount and the quote methods — are safe from any thread and never block. Everything else must run on the main server thread and will throw IllegalStateException if it does not. There is nothing in this API that is safe to call from an async task and also changes something.

Where to go next

API reference — every method in detail.
Events — reacting instead of polling, which is usually what you actually want.
Examples — a sale logger, a category tax, and a shop that lists on a player's behalf.