Skip to content

XereoNet/SpaceGDN

Repository files navigation

This API uses Semantic Versioning. The current version is 0.0.0, developing towards 0.1.0.

#Version 1.0.0 Version 1 of the API does not require any authentication to use. It is limited to a maximum of 1000 requests per hour per IP. If this maximum is exceeded, the API will return error 492 (in accordance with RFC 6585) in its errors (see below).

Jars are layered by Type > Channel > Version > Build. For example, a standard Craftbukkit build could be chained as Craftbukkit > Recommended > 1.6.4 > 1850, for the last recommended build of version 1.6.4. The API is RESTful API.

All requests to the API receive the following response format. success will either be set to true or false. errors will always be set, as an array of objects (see Errors below). In successful responses, errors will be empty. results will be the results of the query, and specified in the sections below. See the Paginated Results section for information on the pagination properties.

{
	success: true|false,
	error: [],
	results: ...,
	pages: ...
}

##Errors Error are returned in the error property in each request response. Each error is an object consisting of two parts: a numeric error code (should be used for any internal testing) and a textual error message (for debugging or display). When an error occurs, a HTTP 400 code will be returned. The API may return the following errors:

  • { code: 492, message: 'API rate limit exceeded.' } - This error is returned if the rate limit, 1000 requests per hour, is exceeded.
  • { code: 1000, message: 'Expecting digit, not "foo".' } - This error is returned if a string was found in place of a digit, as would occur in the request GET /jar/foo, for example.
  • { code: 1001, message: 'Invalid hierarchy order of "foo". Parts must be given in the order of jar, channel, version, and build.' } - This error is returned if request parts are given in the wrong order, like GET /channel/2/jar. This doesn't make sense, as "jars" own "channels", not the other way around.
  • { code: 1002, message: 'Invalid hierarchy part "foo". Must be one of jar, channel, version, or build.' } - This error is returned if an invalid request part, such as "foo" is given in place of a resource.

##Resources

The following resources are available in this API:

  • jar - the type of jar, such as "Craftbukkit" or "FTB".
  • channel - channel of the jar or channel, such as "Recommended" or "MindCrack".
  • version - Minecraft version to correspond to, such as "1.6.2" or "1.7.2"
  • build - the jar build number, such as 1850.

Note: some responses return a last updated time, created at time, etc. These are always the UTC Unix timestamp.

##Chaining

The data is hierarchical, so chaining may be done in the order of Type > Channel > Version > Build. For example, all of the following would be valid requests:

GET /jar/:id/channel # Lists all channels for the given server jar
GET /jar/:id/build # Jumps down the chain and lists builds for the given jar
GET /channel/:id/build # Starts at the channel/channel, and lists all builds inside of it
GET /jar/:id/channel/:id/version/:id/build # Verbosely gets all builds for the given version

##Paginated Results In order to prevent flooding, results are paginated automatically to 100 results. Page information is always returned in the response object. Non-paginated results will simply display as having 1 page. Pages can be navigated to by passing the property page in the URL. For example:

GET /jar/1/build?page=10

A page response object looks something like this. Properties are fairly self-explanitory:

{
	pages: 42,
	has_next: true,
	has_prev: true,
	current_page: 8,
	total_items: 4244
}

##Requests

###Type

The jar is the highest level in the hierarchy. The following requests are valid:

####Request List all available jar jars:

GET: /jar

#####Response Returns an array of all jars available in the API. See the below request for contents of each jar object. Example:

{
	success: true,
	error: {},
	results: [{ ... }, { ... }, { ... }, ...]
}

#####Request Show information on a single jar, by ID:

GET: /jar/:id

#####Response Example:

{
	success: true,
	error: {},
	results: {
		'id': 1,
		'name': 'Craftbukkit',
		'site_url': 'http://bukkit.org',
		'updated_at': 1384711375
	}
}

###Channel

Request for jar channels.

#####Request List all available channels.

GET: /channel

#####Response Example:

{
	success: true,
	error: {},
	results: [{ ... }, { ... }, { ... }, ...]
}

#####Request Get information on a single channel, by ID:

GET: /channel/:id

#####Response Example:

{
	success: true,
	error: {},
	results: {
		'id': 1,
		'name': 'Recommended',
		'jar_id': 1,
		'updated_at': 1384711375
	}
}

###Version

Request for versions.

#####Request List all available versions. Note that versions may not be able to be resolved for some Jenkins sources, such as Bungeecord. In this case, version will be zero.

GET: /version

#####Response

Example:

{
	success: true,
	error: {},
	results: [{ ... }, { ... }, { ... }, ...]
}

#####Request Get information on a single channel, by ID:

GET: /channel/:id

#####Response Example:

{
	success: true,
	error: {},
	results: {
		'id': 1,
		'version': '1.6.4',
		'name_id': 1,
		'updated_at': 1384711375
	}
}

###Build

Request for all builds in a channel.

#####Request List all available builds.

GET: /build

#####Response Example:

{
	success: true,
	error: {},
	results: [{ ... }, { ... }, { ... }, ...]
}

#####Request Get information on a single build, by ID:

GET: /build/:id

#####Response

Currently the checksum and size properties are not available for Jenkins-based sources. You can use these if they are there, but don't depend upon them!

Example:

{
	success: true,
	error: {},
	results: {
		'id': 1,
		'version_id': 1,
		'build': 1234,
		'size': 15295007,
		'checksum': '5c3d125265a806e842fe97625658fb1c',
		'url': 'http://dl.bukkit.org/downloads/craftbukkit/get/02389_1.6.4-R2.0/craftbukkit.jar',
		'created_at': 1384711375
	}
}