m (→Introduction: Reworded API key generation to make it more prominant) |
@DeletedUser40283194 (talk | contribs) (Fix Gravity's GH username) |
||
Line 58: | Line 58: | ||
== Code examples == |
== Code examples == |
||
− | A simple example of API usage is BukkitDev lead Gravity's [https://github.com/ |
+ | A simple example of API usage is BukkitDev lead Gravity's [https://github.com/gravitylow/ServerModsAPI-Example 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 [https://github.com/ |
+ | A more complex example is provided by Gravity's [https://github.com/gravitylow/Updater 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. |
<blockquote><source lang="java">Updater updater = new Updater(this, 55555, this.getFile(), UpdateType.NO_DOWNLOAD, true); |
<blockquote><source lang="java">Updater updater = new Updater(this, 55555, this.getFile(), UpdateType.NO_DOWNLOAD, true); |
Revision as of 18:52, 14 October 2013
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/.
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", "gameVersion":"1.4.7", "name":"v0.1", "projectId":33921, "releaseType":"beta" } ]
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()); }