Difference between revisions of "API Overview"

Revision as of 15:44, 24 April 2012

King Arthur's Gold has an API under development. This page and others on the kagwiki will serve as official documentation for how to use this API.

The API is planned to be 100% RESTful and uses JSON for all responses. HTTP request verbs and response codes are used appropriately and should be obeyed.

The API is/will be used for the following:

• Client authentication (both when the client opens and when joining a server)
• Server registration in the master list
• Client retrieval of the server list and server details
• Retrieving a forum member's Avatar URL

Future uses:

• Third party retrieval of forum and KAG account profile information (avatars, signatures, etc)
• Querying for KAG account status (gold/not activated/banned)
• Sekrit features to be determined/announced

Some of the features documented here are intended for internal use by components of KAG only. They may technically be usable by third party applications and sites, however their use is discouraged for various reasons. Documented features which fall into this category will have warnings posted.

Documentation here may currently include API features which are not fully implemented. Pages will generally indicate the implementation status of features (In order of least to most complete: Planned, Under Development, Partial Implementation, Completed, Mature)

In general, requests are answered with appropriate HTTP status codes. Responses may also include a 'statusMessage' and 'statusSubCode' to further detail certain failures. A 'message' is a human-readable error message which can be used by a client as rudimentary output to display to a user. A 'statusSubCode' is almost like an ENUM - so that programmatic decisions can be made by clients about what to do in certain situations. For example, a 403 may be because access is forbidden to an object based on permissions, because the account used for authentication is not active, or because the account used for auth is banned. The formermost is very straightforward so no 'statusMessage' and 'statusSubCode' is included. The latter two would be sent with a 'statusMessage' and 'statusSubCode'. The 'message' contents are not intended to be consumed programmatically and therefore are not documented in detail. The statusSubCode values are further documented, see statusSubCode

Authentication

Some requests require authentication, which is provided via HTTP Basic Authentication. You can refer to RFC 2617 Section 2 for details about how to form an Authentication header for Basic auth. Here is a pseudo-Python example of a valid Authorization header:

authorization = "Authorization: Basic %s" % base64.b64encode("%s:%s"%username,password)

To view a full list of API-related pages, see Category:API