ServerMods API

Introduction

The Curse server mods API allows developers to receive information on the latest available files for their project in JSON form. The API has two available endpoints, which should be requested with the GET HTTP method. An API key can be optionally specified with the use of the X-API-Key header - otherwise the API can be used anonymously. The base URL for all requests is https://api.curseforge.com/servermods/. Developers should make use of the User-Agent header and use it to identify their application in the form of "User-Agent: {Application Name}/v{version} (by {author})". Care should be taken to ensure that API Keys are not inadvertently hard-coded or embedded into applications or plugins.

We encourage server admins to use their own API key which can be generated at https://dev.bukkit.org/home/servermods-apikey/. Please note that the server mods API key is completely separate to the BukkitDev API key (https://dev.bukkit.org/home/api-key/) which should never be used in an updater.

Searching for project IDs

The projects endpoint allows developers to convert a slug (e.g. worldedit) found in the BukkitDev plugin URL to its numeric identifier. The endpoint accepts searches for matching projects from the supplied search term. The search term should be passed in via the search GET argument.

An example request:

URL: https://api.curseforge.com/servermods/projects?search=worldedit

Output:

[
   {
      "id":54713,
      "name":"LimitedWorldEdit",
      "slug":"limitedworldedit",
      "stage":"beta"
   },
   {
      "id":55226,
      "name":"AsyncWorldEdit",
      "slug":"async_worldedit",
      "stage":"beta"
   },
   {
      "id":31043,
      "name":"WorldEdit",
      "slug":"worldedit",
      "stage":"release"
   }
]

Retrieving a file listing for projects

The files endpoint allows developers to obtain a list of the latest normal files attached to a project. The endpoint allows for multiple projects to be looked up at once. The project identifiers should be passed via the projectIds argument, which accepts comma-separated input as well as a single ID.

An example request:

URL: https://api.curseforge.com/servermods/files?projectIds=33921

Output:

[
   {
      "downloadUrl":"http:\/\/servermods.cursecdn.com\/files\/553\/160\/yoda.mp3",
      "fileName":"yoda.mp3",
      "fileUrl":"http:\/\/www.curseforge.com\/files\/553160",
      "gameVersion":"1.4.7",
      "md5":"bc301c973d5572e8126930e5e3cc9d10",
      "name":"v0.1",
      "projectId":33921,
      "releaseType":"beta"
   }
]

The "fileUrl" field gives a link to the file changelog page. In this case it will redirect to http://dev.bukkit.org/bukkit-plugins/bukkitdevtest/files/1-v0-1/. The "md5" field is the MD5 checksum of the file and can be used to ensure that a file has downloaded correctly.

Code examples

A simple example of API usage is BukkitDev lead Gravity's ServerModsAPI-Example project. This code is a simple example of how you can utilize the json-simple library included in Bukkit to query the API and determine the status of a project by its projectId.

A more complex example is provided by Gravity's Updater, a full-featured class you may use in your plugin. An example usage is below, utilizing Updater to check for updates and choosing not to download them.

Updater updater = new Updater(this, 55555, this.getFile(), UpdateType.NO_DOWNLOAD, true);
if (updater.getResult() == UpdateResult.UPDATE_AVAILABLE) {
    this.getLogger().info("New version available! " + updater.getLatestName());
}

Care should be taken to ensure that you comply with the guidelines when making use of an automatic update checker or downloader.