56106f71f5647998520d07e2c275d3db8642bc98

everything you need to know about the API

Basic usage

We offer two different API URIs. One's just more human-readable and a little better on the bandwidth side of things than the other. It's entirely up to you what you want to use. All parameters can be sent as POST, excepting for the first URI which requires you send your user/application keys in the URI's path, so you don't need to send them at all in that case.

Option 1: Gatecamper Optimised URI

http(s)://www.gatecamper.org/api/:application_key/:user_key/resourcebase/resourceURI.xml.aspx? \
        other_args=other_values

This method is recommended, but optional. You pass your application's key and user key in as part of the path rather than as other options. You can pass any options you want on the end of the request as GET or as POST parameters.

Option 2: Standard EVE API URI

http(s)://www.gatecamper.org/api/resourcebase/resourceURI.xml.aspx? \
        application_key=:application_key&user_key=:user_key&other_args=other_values

This method works particularly well if you don't want to make any changes to your application. Gatecamper will behave exactly as normal, but instead of sending API key and User ID parameters, you send your Gatecamper parameters as GET or POST along with any other parameters like characterID or beforeRefID.

Gatecamper-Specific Error Messages

In order to maintain interoperability with standard libraries, Gatecamper will deliver the closest EVE API error and code in the usual format whenever an error occurs. Where this message or code may be confusing, a gc_error block is added to the response.

<eveapi version="2" gatecamper_version="1.0-devel">
        <error code="203">Consumer could not be loaded</error>
        <gc_error code="500">Invalid consumer specified. Please check your application key.</gc_error>
        <currentTime>2008-05-28 02:06:29</currentTime>
        <cachedUntil>2008-05-28 02:11:29</cachedUntil>
        </eveapi>

A small amount of time is added to the cachedUntil parameter to prevent automated retries from swamping the servers, however the request is not actually cached and may be retried, assuming that the EVE API server was not contacted.

Caching Behaviour

Gatecamper internally caches responses to reduce load on the EVE API servers and to accomodate requests when the EVE API servers are offline or unreachable. Caching behaviour is simply to cache requests until the timer expires and the cache can be updated from the EVE API servers at which point a new request will be made to update the cache.

If the EVE API servers are offline or otherwise unavailable, the cache will be served regardless, and the cacheduntil timer set to 15 minutes in the future when a retry may be made.

Additional attributes

Several attributes are added to Gatecamper API requests.

The <eveapi> tag

This tag gains two attributes.

gatecamper_version: Shows the version of Gatecamper. Useful for debugging requests.
gatecamper_cache_state: Shows the state of the cached response. Can be one of:

NEW - Gatecamper has no cache, and so the EVE API servers were involved in this request
UPDATED - Gatecamper has this cached but just updated from the EVE API servers
NO_UPDATE_NEEDED - Gatecamper has this cached and does not need to update it
EVE_API_UNAVAIL_BUT_CACHED - Gatecamper needs to update it but cannot, so is serving an old cached copy instead.

The <cachedUntil> tag

This tag may gain a comment if it has been adjusted from the document's value. This will be in the gc_comment attribute. For example:

<cachedUntil gc_comment="+15M, EVE API unavailable, retry later">2008-05-28 03:04:14</cachedUntil>
        This is intended more as a debugging tool than a dependenable variable.

Transport encryption

Gatecamper provides the option to use AES-256 Secure Socket Layer encryption on all API requests and most pages. Static content pages on the site automatically degrade to HTTP to reduce loading. All other pages can be linked to as SSL pages (HTTPS).

The API URIs above will work with both HTTPS and HTTP protocols. HTTPS is strongly encouraged for the security of your users.

Short Keys

Gatecamper supports 'short keys' for mobile applications where typing a full, 64-character key would be extremely inconvenient for the application's users.

To use short keys, the user_key argument becomes short_user_key, and the short key should be used rather than the full key. A length check is recommended in your application to ensure the user does not type in the full length key. Short keys are 10 characters in length.