Difference between revisions of "API Overview"

Latest revision as of 04:39, 21 January 2013

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)

Caching and Other Best Practices

Guidelines for caching API resources can be found at API Caching Guidelines. Other important points:

• Please attempt to query the API over IPv6 when available. You should ask your ISP(s) about IPv6 deployment/accesss, for more information read This forum thread by FliesLikeABrick. The reasoning for this is that the KAG datacenter space is very constrained on IPv4 address space, whereas we have near infinite IPv6 address space available. This makes it easier to scale the API for IPv6 query load than IPv4, since we can add IPv6-only nodes to the API load balancing
• The API may be rate limited in the future for unauthenticated API calls. There is currently no way to register for higher API query rates (something like an "API key" that grants you higher limits), therefore all uses are unauthenticated. If rate limiting is implemented, it will be based on queries per connection and queries per IP address (most likely per hour)
• When at all possible, re-use your connections to the API! This means using libcurl or similar when available. Re-using existing connections will allow you higher query rates/volumes as the initial SSL handshake is one of the most expensive parts of the API for us to scale. Re-using your connections to the API will also increase your performance significantly, especially if you are far away from the API servers (network-wise on the Internet)
• Please set a User-Agent string in your HTTP requests. We need to be able to identify who is responsible for which traffic so that we can contact you in case we see broken calls, abuse, or some kind of bug/flood/etc. Ideally the UA string would indicate something like what site it is being used on (or what person/company), and/or contact information for the tool being used. Like if you have a control panel website or similar using this, it would be good to say "Foo Bar KAG Server Rentals Control Panel/<URL>". It is up to you (the 3rd party API consumer) to decide what level of information is necessary/responsible.

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