User:Drakken Keisterbane/CREST

The Carbon RESTful (CREST) HTTP API is a read and write API to the EVE Universe. It gives the ability to interact with the game cluster in an effective manner from clients and applications other than the EVE game client. Although not all CREST endpoints been released yet, there are plenty of useful public endpoints available at this time, with more being released on a regular basis.

Resources

As of Dec. 2014, no publicly released CREST endpoints support the modification or deletion of resources.

CCP exposes various things in EVE Online as resources, each of which have a canonical URI (Uniform Resource Identifier). CREST allows third-party developers to obtain (and read) representations of these resources by making an appropriate HTTP GET request to the resource's URI. Resources can be appended (written to), by making an appropriate HTTP PUT request, and deleted by making a correct HTTP DELETE request to the resource's URI.

All resources can be reached from the root API entry point URI, which will be shortened to entry point from here forward. Entry points will be discussed more in-depth later, in their own section.

Representations

Resources are represented as "hypermedia documents which link to related resources." (<- cite) The structure that a representation uses is dictated by media types, identifiers used to indicate the type of data files on the internet contain. This means that there is a separate media type for each subsequent version of a given representation. Note that a representation can be appended in order to add new functionality, so applications must be able to ignore any extra unneeded information they may receive. Under normal circumstances, names and attributes in representations are not changed or removed. However, if it is required to changed or remove these, a new version of a representation will be made with the changes. This new representation will be assigned its own media type, and CCP will keep the old version up as long as possible.

It is important to state that applications will always be served the newest version of a representation by default, so that new applications use the newest version. It is very important to explicitly state which version of a given representation you are relying on in order to ensure the continued functionality of your applications, especially if these rely on the structure of a particular version of the representation.

You can specify which version of a representation(s) you'd like your application to deal with by using the Accept header to specify what version of a representation you want to receive (used in HTTP GET requests) and the Content-Type header to specify what version to send out (used in HTTP POST and PUT requests). More information on these these headers can be found here.

Representations in Code

Representations are formatted as JSON (JavaScript Object Notation) objects, containing name/value pairs, nested objects and arrays. Some name and value pairs are optional, and can be omitted by senders when not necessary. Other name/value pairs have default values assigned to them if a value is not explicitly assigned.

There are special names used across all representations that have special significance, and thus can be relied on to be consistent across all versions of a given representation.

• href: Intended to be used as a URI to an external resource.
• name: Intended to be used as a localized, human-readable name for a given resource.
• id: Intended to be used as an identifier for a given resource, which is not human-readable.

The values used in these representations can be of various JSON data types; these are described below.

• string: A JSON string. Ex: "John Doe"
• number: A JSON number - the equivalent of double precision floating point format in Java and other languages. Ex: 65.1231415
• int: A JSON number, which cannot not contain decimals/fractions. Ex: 10
• float: A JSON number that can have a decimal/fraction. Ex: 3.14
• long: An integer value of arbitrary length, formatted as a JSON decimal string. Ex: "672300213144"
• time: A JSON string containing an ISO 8601 formatted combined date and UTC time, with 3 decimal places of precision. Ex: "2013-10-21T13:28:06.419Z" (10/21/13 13:28:6.41)
• array: A JSON array of JSON objects. Ex: [{"firstName":"John", "lastName":"Doe"}, {"firstName":"Anna", "lastName":"Smith"}, {"firstName":"Peter", "lastName":"Jones"}]

Usage

CREST API has two flavors - the public version, which is currently being worked on and the "authed" version. The authenticated CREST is currently only usable by CCP employees, although they plan to release it in due time.

It is important to note that CCP has placed rate limits - restrictions on how often you can make calls to the API in a certain amount of time. As of the time of writing, the rate limits are:

• Rate per Second: 30
• Burst Size: 100

This means that you can make 30 requests to the API per second at most. If there are more than 100 waiting/delayed requests to CREST for a given IP, subsequent requests will be terminated with a HTTP error 503 (Service Temporarily Available) until the number of waiting requests goes back below the burst size.

Note that violation of the specified rate limits may result in an IP ban from CREST.

Entry Points

There are two root entry points available for CREST, one for Tranquility and one for the Singularity test server (Sisi). The entry points below are accurate as of the time of writing.

Tranquility:

http://public-crest.eveonline.com

Singularity:

http://public-crest.sisi.testeveonline.com

Notes

Collections

Many of the endpoints available on CREST will give an overview of an entire set of related resources. For example, the alliance endpoint, with no specification to a particular alliance, will give an overview of all alliances in EVE Online. For the purposes of this guide, we will call these types of endpoints collections.

Since there are usually a very large number of items in a collection, it is often split into pages, each with its own array of objects of an arbitrary length. There is no guarantee that the length of the arrays across pages are equal.

All pages will contain a pageCount name/value pair that indicates the total number of pages in the collection.

In addition, each page will always have a next JSON object, which will contain a name/value pair, named href whose value is a URI that can be used to reach the next page of data in the collection.

Common Object Structures

(todo: fill this in with common object structures to reduce how many times things need to be written down)

Endpoints

Alliances and Corporations

Alliance Info (all)

URI: http://public-crest.eveonline.com/alliances/
Function: Information on all open alliances in EVE Online.
Collection?: Yes.
Structure:

• totalCount_str: A JSON string, which indicates the number of objects in the collection.
• pageCount: A JSON int, which indicates the total number of pages in this collection.
• items: A JSON array, containing an arbitrary amount of objects. Each object in this array contains limited information on an alliance, shown below.
  • href: A JSON object, which contains the information on this alliance.
    • id_str: The alliance id, in the form of a JSON string.
    • shortName: The alliance ticker, in the form of a JSON string.
    • href: A URI which can be used to access more detailed information on this alliance. (see the /alliances/<allianceid:integerType>/ endpoint for more information)
    • id: The alliance id, in the form of a JSON number.
    • name: The name of the alliance, in the form of a JSON string.
• next: A JSON object, which contains information on accessing the next page of data.
  • href: A URI that can be used to access the next page of this collection.
• totalCount: A JSON int, which indicates the number of objects in the collection.
• pageCount_str: A JSON string, which indicates the total number of pages in this collection.

Alliance Info (single)

URI: http://public-crest.eveonline.com/alliances/<allianceid:integerType>/
Function: Information on a given open alliance in EVE Online, specified by the alliance id.
Collection?: No.
Structure:

• startDate: A JSON timestamp, indicating the date and time the alliance opened.
• corporationsCount: A JSON int, which indicates the total number of corporations in the alliance.
• description: The alliance's description, in the form of a JSON string.
• executorCorporation: A JSON object, which contains information on the executor corporation of the alliance.
  • name: The executor corporation's name, in the form of a JSON string.
  • isNPC: A JSON boolean, which indicates whether this corporation is an NPC corporation or not.
  • href: A URI which can be used to access more detailed information on this corporation. (see the /corporations/<corporationid:integerType>/ endpoint for more information)
  • id_str: The corporation id, in the form of a JSON string.
  • logo: An object containing links to corporation logos of various sizes.
    • 32x32: A JSON object, containing a name/value pair whose value is a link to a corporation logo image. The size of the linked image is indicated by the name of this object (32x32 in this case).
    • 64x64: Same as 32x32 in structure, just double the size.
    • 128x128: Same as 64x64 in structure, just double the size.
    • 256x256: Same as 128x128 in structure, just double the size.
  • id: The corporation id, in the form of a JSON int.
• corporationsCount_str: The amount of corporations in the alliance, as a JSON int.
• deleted: Whether the corporation has been closed or not, as a JSON boolean.
• creatorCorporation: A JSON object which contains information on the corporation that created the alliance.
  • Same structure as the executorCorporation object above.
• url: The alliance URL, as a JSON string.
• id_str: The alliance id, as a JSON string.
• creatorCharacter: A JSON object containing information about the character that created the alliance.
  • name: The character's name, as a JSON string.
  • isNPC: Whether this character is an NPC or not, as a JSON boolean.
  • href: A URI that can be used to obtain more information on this character.
  • capsuleer: A URI that can be used to get the capsuleer information for this character.
  • portrait: An object containing links to character portraits of various sizes.
    • 32x32: A JSON object, containing a name/value pair whose value is a link to this character's portrait. The size of the linked image is indicated by the name of this object (32x32 in this case).
    • 64x64: Same as 32x32 in structure, just double the size.
    • 128x128: Same as 64x64 in structure, just double the size.
    • 256x256: Same as 128x128 in structure, just double the size.
  • id: The character id, in the form of a JSON int.
  • id_str: The character id, in the form of a JSON string.
• corporations: A JSON array that contains information on all the corporations in the alliance.
  • All objects in this array have the same structure as the executorCorporation and creatorCorporation objects above.
• shortName: The alliance ticker, in the form of a JSON string.
• id: The alliance id, as a JSON int.
• name: The name of the alliance, as a JSON string.

Other

Killmail

To obtain the required killmail hash for the killmail endpoint, you can use the formula below:

killmailHash = sha1(victimCharacterID + attackerCharacterID + shipTypeID + killTime)

Note: All variables in this formula are strings, and adding them in this way represents concatenation, not addition of the ids as integers.

Where the following is true:

• victimCharacterID: The character id of the victim, as a string.
• attackerCharacterID: The character id of the attacker that got the final blow. If the attacker with the final blow is an NPC (characterID == 0), this is the string "None" instead.
• shipTypeID: The type id of the victim's ship.
• killTime: The time the kill occurred, as a 64-bit timestamp (read unix timestamp * 10,000,000).