# NameMCAPI (EarthPol)<\/p>\n
NameMCAPI is a lightweight Paper\/Folia-safe plugin that exposes several of NameMC\u2019s **undocumented public API endpoints** as a shared **Bukkit service**.<\/p>\n
It is designed to be used by other plugins in the EarthPol ecosystem (or elsewhere) without scraping HTML or blocking the main server thread.<\/p>\n
All requests are asynchronous and optionally cached.<\/p>\n
—<\/p>\n
Features<\/p>\n
– Async, non-blocking HTTP requests
\n– Bukkit Services API integration
\n– Optional TTL-based response caching
\n– Cache bypass for \u201cfetch latest\u201d calls
\n– Paper & Folia compatible
\n– Clean separation between API and implementation<\/p>\n
—<\/p>\n
Supported NameMC Endpoints<\/p>\n
The following NameMC endpoints are currently supported:<\/p>\n
– `GET \/profile\/{uuid}\/friends`
\n– `GET \/profile\/{uuid}\/friends?with={uuid}`
\n– `GET \/server\/{domain}\/likes`
\n– `GET \/server\/{domain}\/likes?profile={uuid}`<\/p>\n
—<\/p>\n
Installation<\/p>\n
1. Place `NameMCAPI.jar` into your `\/plugins` directory
\n2. Restart the server
\n3. The API service will register automatically<\/p>\n
No commands or permissions are required.<\/p>\n
—<\/p>\n
Configuration<\/p>\n
“`yml
\nnamemc:
\n base-url: “https:\/\/api.namemc.com”
\n http-timeout-ms: 6000
\n cache-ttl-ms: 60000
\n“`<\/p>\n
### Configuration Options<\/p>\n
– `base-url`
\n – Defaults to `https:\/\/api.namemc.com`<\/p>\n
– `http-timeout-ms`
\n – HTTP request timeout in milliseconds<\/p>\n
– `cache-ttl-ms`
\n – Time-to-live for cached responses
\n – Set to `0` to disable caching entirely<\/p>\n
—<\/p>\n
Using NameMCAPI in Other Plugins<\/p>\n
NameMCAPI exposes a Bukkit service called `NameMCAPIService`.<\/p>\n
1. Obtaining the Service<\/p>\n
“`java
\nimport com.earthpol.namemc.api.NameMCAPIService;
\nimport org.bukkit.Bukkit;<\/p>\n
NameMCAPIService nameMC =
\n Bukkit.getServicesManager().load(NameMCAPIService.class);<\/p>\n
if (nameMC == null) {
\n getLogger().severe(“NameMCAPI not found! Is the plugin installed?”);
\n return;
\n}
\n“`<\/p>\n
This should typically be done once in `onEnable`.<\/p>\n
—<\/p>\n
2. Fetching a Player\u2019s Friends List<\/p>\n
“`java
\nUUID uuid = UUID.fromString(“d550441b-5fcf-448c-a756-5fa391b89a46”);<\/p>\n
\/\/ false = fetch latest, true = use cache
\nnameMC.getFriends(uuid, false).thenAccept(friends -> {
\n getLogger().info(“Friend count: ” + friends.size());
\n});
\n“`<\/p>\n
—<\/p>\n
3. Checking if Two Profiles Are Friends<\/p>\n
“`java
\nUUID a = UUID.fromString(“403e6cb7-a6ca-440a-8041-7fb1e579b5a5”);
\nUUID b = UUID.fromString(“ac62cc72-ce09-4fd4-9018-38b92ef4d619”);<\/p>\n
nameMC.areFriends(a, b, true).thenAccept(areFriends -> {
\n if (areFriends) {
\n getLogger().info(“They are friends on NameMC”);
\n }
\n});
\n“`<\/p>\n
—<\/p>\n
4. Getting Server Like Count<\/p>\n
“`java
\nnameMC.getServerLikes(“play.earthpol.com”, true)
\n .thenAccept(likes ->
\n getLogger().info(“Server likes: ” + likes)
\n );
\n“`<\/p>\n
—<\/p>\n
5. Checking if a Player Liked a Server<\/p>\n
“`java
\nUUID profile = UUID.fromString(“3bd5b91a-7532-4acf-bd2a-2a739206865b”);<\/p>\n
nameMC.hasProfileLikedServer(“play.earthpol.com”, profile, false)
\n .thenAccept(liked -> {
\n if (liked) {
\n getLogger().info(“Player has liked the server”);
\n }
\n });
\n“`<\/p>\n
—<\/p>\n
Threading Notes (IMPORTANT)<\/p>\n
All callbacks run **off the main thread**.<\/p>\n
If you need to interact with Bukkit objects (players, worlds, scoreboards, etc.), you must switch back to the main thread:<\/p>\n
“`java
\nnameMC.getFriends(uuid, true).thenAccept(friends -> {
\n Bukkit.getScheduler().runTask(this, () -> {
\n player.sendMessage(“You have ” + friends.size() + ” NameMC friends”);
\n });
\n});
\n“`<\/p>\n
—<\/p>\n
Maven Dependency (BitworksMC Nexus)<\/p>\n
NameMCAPI is published to the BitworksMC Nexus repository and can be consumed directly via Maven.<\/p>\n
1. Add the repository<\/p>\n
“`xml “`xml —<\/p>\n Design Notes<\/p>\n – NameMCAPI does **not** scrape HTML —<\/p>\n License \/ Disclaimer<\/p>\n This project is **not affiliated with NameMC** or Mojang\/Microsoft.<\/p>\n NameMC endpoints are undocumented and may change or disappear at any time.<\/p>\n Use at your own risk.<\/p>\n","protected":false},"excerpt":{"rendered":" NameMCAPI is a lightweight Paper\/Folia-safe plugin that exposes several of NameMC\u2019s undocumented public API endpoints as a shared Bukkit service.<\/p>\n","protected":false},"featured_media":108622,"template":"","meta":{"_minecraft_slug":"namemcapi","_minecraft_project_id":"bIC64kUf","_minecraft_author":"GoodrichDev","_minecraft_license":"CC-BY-SA-4.0","_minecraft_downloads":14,"_minecraft_follows":0,"_minecraft_client_side":"unsupported","_minecraft_server_side":"required","_minecraft_storage_type":"zip","_minecraft_archive_name":"namemcapi.zip","_minecraft_size_bytes":16198,"_minecraft_version_count":1,"_minecraft_updated_at":"2026-05-15T22:54:13.438237Z","_minecraft_date_created":"2026-01-31T20:56:17.668248Z","_minecraft_date_modified":"2026-01-31T02:16:37.616735Z","_minecraft_project_url":"https:\/\/modrinth.com\/mod\/namemcapi","_minecraft_icon_attachment_id":108622,"_minecraft_imported_at":"2026-06-06T06:47:18+00:00","_minecraft_import_hash":"7da5cc96fdd11d5c51f410be2bb56487","_minecraft_versions":"","_minecraft_links":"","_minecraft_gallery":"","_minecraft_api_metadata":""},"mod_category":[125,873,867,92],"mod_loader":[131],"minecraft_version":[59,36,60,93,94,101,102,62,37,40,41,73,74,38,78,79,80,81,82],"class_list":["post-108621","mod","type-mod","status-publish","has-post-thumbnail","hentry","mod_category-folia","mod_category-library","mod_category-social","mod_category-utility","mod_loader-folia","minecraft_version-1-20","minecraft_version-1-20-1","minecraft_version-1-20-2","minecraft_version-1-20-3","minecraft_version-1-20-4","minecraft_version-1-20-5","minecraft_version-1-20-6","minecraft_version-1-21","minecraft_version-1-21-1","minecraft_version-1-21-10","minecraft_version-1-21-11","minecraft_version-1-21-2","minecraft_version-1-21-3","minecraft_version-1-21-4","minecraft_version-1-21-5","minecraft_version-1-21-6","minecraft_version-1-21-7","minecraft_version-1-21-8","minecraft_version-1-21-9"],"yoast_head":"\n
\n
\n
\n
\n
\n <\/repository>
\n<\/repositories>
\n“`
\n2. Add the dependency<\/p>\n
\n
\n
\n
\n
\n
\n<\/dependency>
\n“`<\/p>\n
\n– Uses NameMC\u2019s publicly accessible JSON endpoints
\n– Responses and endpoints are undocumented and may change
\n– Failures are not cached
\n– Cache deduplicates in-flight requests to avoid stampedes<\/p>\n