User:Drakken Keisterbane/CREST
This article or section is in the process of an expansion or major restructuring. You are welcome to assist in its construction by editing it as well.
If this article or section has not been edited in several days, please remove this template.
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.
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.
Entry Points
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:
