User:Drakken Keisterbane/CREST: Difference between revisions

(8 intermediate revisions by 2 users not shown)

Line 1:

~~{{WIP}}~~

~~=TODO=~~

* Explain each endpoint in detail.

* Polish explanation on API usage.

* Try to provide code examples/applications for each endpoint.

~~=Introduction=~~

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.

Line 59:

Line 51:

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.

==Entry Points==

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''': {{code | http://public-crest.eveonline.com}}

'''Singularity''': {{code | 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)

~~There are two root entry points available for CREST, one for '''Tranquility''' and one for the '''Singularity''' test server (Sisi).~~

~~(todo: add fancy boxes for each entry point)~~

~~Tranquility:~~

~~Singularity:~~

==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.

===Market===

===Industry===

===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).

=External Resources=

@@ Line 1: / Line 1: @@
-{{WIP}}
-=TODO=
-* Explain each endpoint in detail.
-* Polish explanation on API usage.
-* Try to provide code examples/applications for each endpoint.
-=Introduction=
 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.
@@ Line 59: / Line 51: @@
 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.
-==Entry Points==
+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''': {{code | http://public-crest.eveonline.com}}
+'''Singularity''': {{code | 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)
-There are two root entry points available for CREST, one for '''Tranquility''' and one for the '''Singularity''' test server (Sisi).
-(todo: add fancy boxes for each entry point)
-Tranquility:
-Singularity:
 ==Endpoints==
+===Alliances and Corporations===
+====Alliance Info (all)====
+<br />'''URI''': http://public-crest.eveonline.com/alliances/
+<br />'''Function''': Information on all open alliances in EVE Online.
+<br />'''Collection?''': Yes.
+<br />'''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)====
+<br />'''URI''': http://public-crest.eveonline.com/alliances/<allianceid:integerType>/
+<br />'''Function''': Information on a given open alliance in EVE Online, specified by the alliance id.
+<br />'''Collection?''': No.
+<br />'''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.
 ===Market===
 ===Industry===
+===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).
 =External Resources=