Update to v4

Veyronity · Veyronity · commit c728ce674acf · 2026-03-06T15:23:26.000+02:00
- Move deprecated endpoints to /legacy/
- Update endpoints to accept an API key, currently only the player &amp; shop endpoints use it
- Add QuickShop integratoin to allow players to lookup their own shops
- Allow players to use their API keys to query their resident status, even if they have opted out
- Add permissions for api command &amp; key management
diff --git a/gradle.properties b/gradle.properties
@@ -1,5 +1,5 @@
 group = net.earthmc.emcapi
-version = 3.1.0-SNAPSHOT
+version = 4.0.0-SNAPSHOT
 description = EMCAPI
 
 org.gradle.configuration-cache=true
diff --git a/src/main/java/net/earthmc/emcapi/EMCAPI.java b/src/main/java/net/earthmc/emcapi/EMCAPI.java
@@ -6,6 +6,7 @@
 import jakarta.servlet.http.HttpServletResponse;
 import net.earthmc.emcapi.integration.Integrations;
 import net.earthmc.emcapi.manager.EndpointManager;
+import net.earthmc.emcapi.manager.LegacyEndpointManager;
 import net.earthmc.emcapi.sse.SSEManager;
 import net.earthmc.emcapi.sse.listeners.ShopSSEListener;
 import net.earthmc.emcapi.sse.listeners.TownySSEListener;
@@ -47,8 +48,10 @@ public void onEnable() {
         this.pluginIntegrations = new Integrations(this);
         getServer().getPluginManager().registerEvents(this.pluginIntegrations, this);
 
-        EndpointManager endpointManager = new EndpointManager(this);
-        endpointManager.loadEndpoints();
+        if (getConfig().getBoolean("behavior.load_legacy")) {
+            new LegacyEndpointManager(this).loadEndpoints(); // Load retired endpoints and still serve current endpoints at /v3/aurora/
+        }
+        new EndpointManager(this).loadEndpoints();
 
         PluginCommand apiCommand = getCommand("api");
         if (apiCommand == null) {
diff --git a/src/main/java/net/earthmc/emcapi/endpoint/DiscordEndpoint.java b/src/main/java/net/earthmc/emcapi/endpoint/DiscordEndpoint.java
@@ -11,6 +11,7 @@
 import net.earthmc.emcapi.util.HttpExceptions;
 import net.earthmc.emcapi.util.JSONUtil;
 
+import javax.annotation.Nullable;
 import java.util.UUID;
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
@@ -21,7 +22,7 @@ public class DiscordEndpoint extends PostEndpoint<DiscordContext> {
     private static final BadRequestResponse INVALID_TYPE_TARGET = new BadRequestResponse("Your JSON query has an invalid type or target");
 
     @Override
-    public DiscordContext getObjectOrNull(JsonElement element) {
+    public DiscordContext getObjectOrNull(JsonElement element, @Nullable UUID key) {
         JsonObject jsonObject = JSONUtil.getJsonElementAsJsonObjectOrNull(element);
         if (jsonObject == null) {
             throw HttpExceptions.NOT_A_JSON_OBJECT;
@@ -60,7 +61,7 @@ public DiscordContext getObjectOrNull(JsonElement element) {
     }
 
     @Override
-    public JsonElement getJsonElement(DiscordContext context) {
+    public JsonElement getJsonElement(DiscordContext context, @Nullable UUID key) {
         DiscordType type = context.getType();
         String target = context.getTarget();
 
diff --git a/src/main/java/net/earthmc/emcapi/endpoint/LocationEndpoint.java b/src/main/java/net/earthmc/emcapi/endpoint/LocationEndpoint.java
@@ -13,10 +13,13 @@
 import org.bukkit.Bukkit;
 import org.bukkit.Location;
 
+import javax.annotation.Nullable;
+import java.util.UUID;
+
 public class LocationEndpoint extends PostEndpoint<Pair<Integer, Integer>> {
 
     @Override
-    public Pair<Integer, Integer> getObjectOrNull(JsonElement element) {
+    public Pair<Integer, Integer> getObjectOrNull(JsonElement element, @Nullable UUID key) {
         JsonArray jsonArray = JSONUtil.getJsonElementAsJsonArrayOrNull(element);
         if (jsonArray == null) throw new BadRequestResponse("Your query contains a value that is not a JSON array");
 
@@ -40,7 +43,7 @@ public Pair<Integer, Integer> getObjectOrNull(JsonElement element) {
     }
 
     @Override
-    public JsonElement getJsonElement(Pair<Integer, Integer> pair) {
+    public JsonElement getJsonElement(Pair<Integer, Integer> pair, @Nullable UUID key) {
         int x = pair.getFirst();
         int z = pair.getSecond();
 
diff --git a/src/main/java/net/earthmc/emcapi/endpoint/NearbyEndpoint.java b/src/main/java/net/earthmc/emcapi/endpoint/NearbyEndpoint.java
@@ -19,13 +19,15 @@
 import org.bukkit.Bukkit;
 import org.bukkit.Location;
 
+import javax.annotation.Nullable;
 import java.util.ArrayList;
 import java.util.List;
+import java.util.UUID;
 
 public class NearbyEndpoint extends PostEndpoint<NearbyContext> {
 
     @Override
-    public NearbyContext getObjectOrNull(JsonElement element) {
+    public NearbyContext getObjectOrNull(JsonElement element, @Nullable UUID key) {
         JsonObject jsonObject = JSONUtil.getJsonElementAsJsonObjectOrNull(element);
         if (jsonObject == null) throw new BadRequestResponse("Your query contains a value that is not a JSON object");
 
@@ -64,7 +66,7 @@ public NearbyContext getObjectOrNull(JsonElement element) {
     }
 
     @Override
-    public JsonElement getJsonElement(NearbyContext context) {
+    public JsonElement getJsonElement(NearbyContext context, @Nullable UUID key) {
         NearbyType targetType = context.getTargetType();
         int radius = context.getRadius();
         switch (targetType) {
diff --git a/src/main/java/net/earthmc/emcapi/endpoint/ShopEndpoint.java b/src/main/java/net/earthmc/emcapi/endpoint/ShopEndpoint.java
@@ -0,0 +1,52 @@
+package net.earthmc.emcapi.endpoint;
+
+import com.google.gson.JsonElement;
+import com.google.gson.JsonObject;
+import io.javalin.http.BadRequestResponse;
+import net.earthmc.emcapi.EMCAPI;
+import net.earthmc.emcapi.integration.QuickShopIntegration;
+import net.earthmc.emcapi.object.endpoint.PostEndpoint;
+import net.earthmc.emcapi.util.EndpointUtils;
+import net.earthmc.emcapi.util.JSONUtil;
+import org.jspecify.annotations.Nullable;
+import org.maxgamer.quickshop.api.shop.Shop;
+
+import java.util.List;
+import java.util.UUID;
+
+public class ShopEndpoint extends PostEndpoint<List<Shop>> {
+    private final QuickShopIntegration integration;
+
+    public ShopEndpoint(EMCAPI plugin) {
+        this.integration = plugin.integrations().quickShopIntegration();
+    }
+
+    @Override
+    public List<Shop> getObjectOrNull(JsonElement element, @Nullable UUID key) {
+        String string = JSONUtil.getJsonElementAsStringOrNull(element);
+        if (string == null) throw new BadRequestResponse("Your query contains a value that is not a string");
+
+        UUID player;
+        try {
+            player = UUID.fromString(string);
+        } catch (IllegalArgumentException ignored) {
+            return null;
+        }
+
+        integration.throwIfDisabled();
+        return integration.getPlayerShops(player, key);
+    }
+
+    @Override
+    public JsonElement getJsonElement(List<Shop> object, @Nullable UUID key) {
+        JsonObject shopsObject = new JsonObject();
+        int counter = 1;
+        UUID keyOwner = EndpointUtils.getKeyOwner(key);
+        for (Shop shop : object) {
+            if (!shop.getOwner().equals(keyOwner)) continue;
+            shopsObject.add(String.valueOf(counter++), EndpointUtils.getShopObject(shop));
+        }
+
+        return shopsObject;
+    }
+}
diff --git a/src/main/java/net/earthmc/emcapi/endpoint/legacy/DocumentationEndpoint.java b/src/main/java/net/earthmc/emcapi/endpoint/legacy/DocumentationEndpoint.java
@@ -1,4 +1,4 @@
-package net.earthmc.emcapi.endpoint;
+package net.earthmc.emcapi.endpoint.legacy;
 
 import com.google.gson.JsonObject;
 import net.earthmc.emcapi.object.endpoint.GetEndpoint;
diff --git a/src/main/java/net/earthmc/emcapi/endpoint/legacy/MudkipEndpoint.java b/src/main/java/net/earthmc/emcapi/endpoint/legacy/MudkipEndpoint.java
@@ -1,4 +1,4 @@
-package net.earthmc.emcapi.endpoint;
+package net.earthmc.emcapi.endpoint.legacy;
 
 public class MudkipEndpoint {
 
diff --git a/src/main/java/net/earthmc/emcapi/endpoint/legacy/PlayerStatsEndpoint.java b/src/main/java/net/earthmc/emcapi/endpoint/legacy/PlayerStatsEndpoint.java
@@ -1,4 +1,4 @@
-package net.earthmc.emcapi.endpoint;
+package net.earthmc.emcapi.endpoint.legacy;
 
 import com.google.gson.JsonObject;
 import io.papermc.paper.threadedregions.scheduler.ScheduledTask;
@@ -16,7 +16,6 @@
 import java.nio.file.StandardOpenOption;
 import java.util.HashMap;
 import java.util.Map;
-import java.util.concurrent.TimeUnit;
 
 public class PlayerStatsEndpoint {
     private final EMCAPI plugin;
diff --git a/src/main/java/net/earthmc/emcapi/endpoint/towny/NationsEndpoint.java b/src/main/java/net/earthmc/emcapi/endpoint/towny/NationsEndpoint.java
@@ -13,13 +13,14 @@
 import net.earthmc.emcapi.util.EndpointUtils;
 import net.earthmc.emcapi.util.JSONUtil;
 
+import javax.annotation.Nullable;
 import java.util.List;
 import java.util.UUID;
 
 public class NationsEndpoint extends PostEndpoint<Nation> {
 
     @Override
-    public Nation getObjectOrNull(JsonElement element) {
+    public Nation getObjectOrNull(JsonElement element, @Nullable UUID key) {
         String string = JSONUtil.getJsonElementAsStringOrNull(element);
         if (string == null) throw new BadRequestResponse("Your query contains a value that is not a string");
 
@@ -34,7 +35,7 @@ public Nation getObjectOrNull(JsonElement element) {
     }
 
     @Override
-    public JsonElement getJsonElement(Nation nation) {
+    public JsonElement getJsonElement(Nation nation, @Nullable UUID key) {
         JsonObject nationObject = new JsonObject();
 
         nationObject.addProperty("name", nation.getName());
diff --git a/src/main/java/net/earthmc/emcapi/endpoint/towny/PlayersEndpoint.java b/src/main/java/net/earthmc/emcapi/endpoint/towny/PlayersEndpoint.java
@@ -10,14 +10,15 @@
 import net.earthmc.emcapi.object.endpoint.PostEndpoint;
 import net.earthmc.emcapi.util.EndpointUtils;
 import net.earthmc.emcapi.util.JSONUtil;
+import org.jetbrains.annotations.Nullable;
 
 import java.util.List;
 import java.util.UUID;
 
 public class PlayersEndpoint extends PostEndpoint<Resident> {
 
     @Override
-    public Resident getObjectOrNull(JsonElement element) {
+    public Resident getObjectOrNull(JsonElement element, @Nullable UUID key) {
         String string = JSONUtil.getJsonElementAsStringOrNull(element);
         if (string == null) throw new BadRequestResponse("Your query contains a value that is not a string");
 
@@ -28,15 +29,17 @@ public Resident getObjectOrNull(JsonElement element) {
             resident = TownyAPI.getInstance().getResident(string);
         }
 
-        if (resident != null && EndpointUtils.playerOptedOut(resident.getUUID())) {
+        if (resident != null && EndpointUtils.playerOptedOut(resident.getUUID())
+            && !resident.getUUID().equals(EndpointUtils.getKeyOwner(key))
+        ) {
             return null;
         }
 
         return resident;
     }
 
     @Override
-    public JsonElement getJsonElement(Resident resident) {
+    public JsonElement getJsonElement(Resident resident, @Nullable UUID key) {
         JsonObject playerObject = new JsonObject();
 
         playerObject.addProperty("name", resident.getName());
diff --git a/src/main/java/net/earthmc/emcapi/endpoint/towny/QuartersEndpoint.java b/src/main/java/net/earthmc/emcapi/endpoint/towny/QuartersEndpoint.java
@@ -12,13 +12,14 @@
 import net.earthmc.emcapi.util.JSONUtil;
 import org.bukkit.Location;
 
+import javax.annotation.Nullable;
 import java.awt.*;
 import java.util.UUID;
 
 public class QuartersEndpoint extends PostEndpoint<Quarter> {
 
     @Override
-    public Quarter getObjectOrNull(JsonElement element) {
+    public Quarter getObjectOrNull(JsonElement element, @Nullable UUID key) {
         String string = JSONUtil.getJsonElementAsStringOrNull(element);
         if (string == null) throw new BadRequestResponse("Your query contains a value that is not a string");
 
@@ -33,7 +34,7 @@ public Quarter getObjectOrNull(JsonElement element) {
     }
 
     @Override
-    public JsonElement getJsonElement(Quarter quarter) {
+    public JsonElement getJsonElement(Quarter quarter, @Nullable UUID key) {
         JsonObject quarterObject = new JsonObject();
 
         quarterObject.addProperty("name", quarter.getName());
diff --git a/src/main/java/net/earthmc/emcapi/endpoint/towny/TownsEndpoint.java b/src/main/java/net/earthmc/emcapi/endpoint/towny/TownsEndpoint.java
@@ -16,6 +16,7 @@
 import net.earthmc.emcapi.util.EndpointUtils;
 import net.earthmc.emcapi.util.JSONUtil;
 
+import javax.annotation.Nullable;
 import java.util.UUID;
 
 public class TownsEndpoint extends PostEndpoint<Town> {
@@ -26,7 +27,7 @@ public TownsEndpoint(EMCAPI plugin) {
     }
 
     @Override
-    public Town getObjectOrNull(JsonElement element) {
+    public Town getObjectOrNull(JsonElement element, @Nullable UUID key) {
         String string = JSONUtil.getJsonElementAsStringOrNull(element);
         if (string == null) throw new BadRequestResponse("Your query contains a value that is not a string");
 
@@ -41,7 +42,7 @@ public Town getObjectOrNull(JsonElement element) {
     }
 
     @Override
-    public JsonElement getJsonElement(Town town) {
+    public JsonElement getJsonElement(Town town, @Nullable UUID key) {
         JsonObject townObject = new JsonObject();
 
         townObject.addProperty("name", town.getName());
diff --git a/src/main/java/net/earthmc/emcapi/integration/Integrations.java b/src/main/java/net/earthmc/emcapi/integration/Integrations.java
@@ -17,6 +17,7 @@ public class Integrations implements Listener {
     private final QuartersIntegration quartersIntegration;
     private final SuperbVoteIntegration superbVoteIntegration;
     private final MysteryMasterIntegration mysteryMasterIntegration;
+    private final QuickShopIntegration quickShopIntegration;
 
     public Integrations(final EMCAPI plugin) {
         this.plugin = plugin;
@@ -25,6 +26,7 @@ public Integrations(final EMCAPI plugin) {
         this.quartersIntegration = addIntegration(new QuartersIntegration());
         this.superbVoteIntegration = addIntegration(new SuperbVoteIntegration());
         this.mysteryMasterIntegration = addIntegration(new MysteryMasterIntegration());
+        this.quickShopIntegration = addIntegration(new QuickShopIntegration());
     }
 
     private <T extends Integration> T addIntegration(final T integration) {
@@ -50,6 +52,10 @@ public MysteryMasterIntegration mysteryMasterIntegration() {
         return this.mysteryMasterIntegration;
     }
 
+    public QuickShopIntegration quickShopIntegration() {
+        return quickShopIntegration;
+    }
+
     @EventHandler
     public void onPluginEnable(final PluginEnableEvent event) {
         final Integration integration = integrations.get(event.getPlugin().getName());
diff --git a/src/main/java/net/earthmc/emcapi/integration/QuickShopIntegration.java b/src/main/java/net/earthmc/emcapi/integration/QuickShopIntegration.java
@@ -0,0 +1,25 @@
+package net.earthmc.emcapi.integration;
+
+import net.earthmc.emcapi.util.EndpointUtils;
+import org.maxgamer.quickshop.QuickShop;
+import org.maxgamer.quickshop.api.shop.Shop;
+
+import java.util.List;
+import java.util.UUID;
+
+public class QuickShopIntegration extends Integration {
+
+    public QuickShopIntegration() {
+        super("QuickShop");
+    }
+
+    public List<Shop> getPlayerShops(UUID player, UUID key) {
+        if (!isEnabled()) {
+            return List.of();
+        }
+        if (!player.equals(EndpointUtils.getKeyOwner(key))) {
+            return List.of();
+        }
+        return QuickShop.getInstance().getShopManager().getPlayerAllShops(player);
+    }
+}
diff --git a/src/main/java/net/earthmc/emcapi/manager/EndpointManager.java b/src/main/java/net/earthmc/emcapi/manager/EndpointManager.java
diff --git a/src/main/java/net/earthmc/emcapi/manager/LegacyEndpointManager.java b/src/main/java/net/earthmc/emcapi/manager/LegacyEndpointManager.java
diff --git a/src/main/java/net/earthmc/emcapi/object/endpoint/PostEndpoint.java b/src/main/java/net/earthmc/emcapi/object/endpoint/PostEndpoint.java
diff --git a/src/main/java/net/earthmc/emcapi/util/EndpointUtils.java b/src/main/java/net/earthmc/emcapi/util/EndpointUtils.java
diff --git a/src/main/java/net/earthmc/emcapi/util/JSONUtil.java b/src/main/java/net/earthmc/emcapi/util/JSONUtil.java
diff --git a/src/main/resources/config.yml b/src/main/resources/config.yml
diff --git a/src/main/resources/plugin.yml b/src/main/resources/plugin.yml

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-package net.earthmc.emcapi.endpoint;`
	`1`	`+package net.earthmc.emcapi.endpoint.legacy;`
`2`	`2`
`3`	`3`	`import com.google.gson.JsonObject;`
`4`	`4`	`import net.earthmc.emcapi.object.endpoint.GetEndpoint;`