NameMCAPI

NameMCAPI (EarthPol)

NameMCAPI is a lightweight Paper/Folia-safe plugin that exposes several of NameMC's undocumented public API endpoints as a shared Bukkit service.

It is designed to be used by other plugins in the EarthPol ecosystem (or elsewhere) without scraping HTML or blocking the main server thread.

All requests are asynchronous and optionally cached.

Features

• Async, non-blocking HTTP requests
• Bukkit Services API integration
• Optional TTL-based response caching
• Cache bypass for "fetch latest" calls
• Paper & Folia compatible
• Clean separation between API and implementation

Supported NameMC Endpoints

The following NameMC endpoints are currently supported:

• GET /profile/{uuid}/friends
• GET /profile/{uuid}/friends?with={uuid}
• GET /server/{domain}/likes
• GET /server/{domain}/likes?profile={uuid}

Installation

1. Place NameMCAPI.jar into your /plugins directory
2. Restart the server
3. The API service will register automatically

No commands or permissions are required.

Configuration

namemc:
  base-url: "https://api.namemc.com"
  http-timeout-ms: 6000
  cache-ttl-ms: 60000

Configuration Options

• base-url

  • Defaults to https://api.namemc.com

• http-timeout-ms

  • HTTP request timeout in milliseconds

• cache-ttl-ms

  • Time-to-live for cached responses
  • Set to 0 to disable caching entirely

Using NameMCAPI in Other Plugins

NameMCAPI exposes a Bukkit service called NameMCAPIService.

1. Obtaining the Service

import com.earthpol.namemc.api.NameMCAPIService;
import org.bukkit.Bukkit;

NameMCAPIService nameMC =
        Bukkit.getServicesManager().load(NameMCAPIService.class);

if (nameMC == null) {
    getLogger().severe("NameMCAPI not found! Is the plugin installed?");
    return;
}

This should typically be done once in onEnable.

1. Fetching a Player's Friends List

UUID uuid = UUID.fromString("d550441b-5fcf-448c-a756-5fa391b89a46");

// false = fetch latest, true = use cache
nameMC.getFriends(uuid, false).thenAccept(friends -> {
    getLogger().info("Friend count: " + friends.size());
});

1. Checking if Two Profiles Are Friends

UUID a = UUID.fromString("403e6cb7-a6ca-440a-8041-7fb1e579b5a5");
UUID b = UUID.fromString("ac62cc72-ce09-4fd4-9018-38b92ef4d619");

nameMC.areFriends(a, b, true).thenAccept(areFriends -> {
    if (areFriends) {
        getLogger().info("They are friends on NameMC");
    }
});

1. Getting Server Like Count

nameMC.getServerLikes("play.earthpol.com", true)
      .thenAccept(likes ->
          getLogger().info("Server likes: " + likes)
      );

1. Checking if a Player Liked a Server

UUID profile = UUID.fromString("3bd5b91a-7532-4acf-bd2a-2a739206865b");

nameMC.hasProfileLikedServer("play.earthpol.com", profile, false)
      .thenAccept(liked -> {
          if (liked) {
              getLogger().info("Player has liked the server");
          }
      });

Threading Notes (IMPORTANT)

All callbacks run off the main thread.

If you need to interact with Bukkit objects (players, worlds, scoreboards, etc.), you must switch back to the main thread:

nameMC.getFriends(uuid, true).thenAccept(friends -> {
    Bukkit.getScheduler().runTask(this, () -> {
        player.sendMessage("You have " + friends.size() + " NameMC friends");
    });
});

Maven Dependency (BitworksMC Nexus)

NameMCAPI is published to the BitworksMC Nexus repository and can be consumed directly via Maven.

1. Add the repository

<repositories>
    <repository>
        <id>bitworksmc-releases</id>
        <url>https://nexus.bitworksmc.com/repository/maven-releases/</url>
    </repository>
</repositories>

1. Add the dependency

<dependency>
    <groupId>com.earthpol</groupId>
    <artifactId>NameMCAPI</artifactId>
    <version>2.0.0</version>
    <scope>provided</scope>
</dependency>

Design Notes

• NameMCAPI does not scrape HTML
• Uses NameMC's publicly accessible JSON endpoints
• Responses and endpoints are undocumented and may change
• Failures are not cached
• Cache deduplicates in-flight requests to avoid stampedes

License / Disclaimer

This project is not affiliated with NameMC or Mojang/Microsoft.

NameMC endpoints are undocumented and may change or disappear at any time.

Use at your own risk.