CREST

CREST (Carbon REST) is a RESTful hypermediaHTTP API that enables read and write access to parts of the EVE universe.

Resources

Things in the EVE universe are exposed as addressable resources with a canonical URI. A representation of a resource can be obtained by making an HTTP GET request to the resource URI. Resources may be updated by making PUT requests to their URI and removed by making DELETE requests to their URI.

All resources are reachable from the root API entry point URI. Clients should not construct URIs, but instead follow URIs included in representations they have received. URIs may be stored as bookmarks, shared in IMs, sent as emails and published on web sites. CCP will endevour to support URIs as permalinks, but client applications should be able to cope with URIs becoming invalid as the API evolves and resources may be served from different locations just as web browsers cope with broken links.

Representations

Resources are represented as hypermedia documents which link to related resources. The structure of representations are described by media types. Clients specify the representation they would like to received using the Accept header of their request and specify which representations they are sending in the Content-Type header.

Representations may be extended to add new relationships and functionality, so clients must ignore all extra data they receive. Representations will never rename or remove attributes.

Where renaming or removing attributes is required to support new functionality, a new version of the representation will be defined as a new media type and the old representation will continue to be supported for as long as possible. The newest version of a representation will be served by default to ensure that new clients are developed using the newest representations. Clients that are widely distributed and not automatically updated should always supply Accept headers if they rely on the structure of representations.

Representations are formatted as JSON objects containing name/value pairs and nested objects and arrays. Some name/value pairs are optional, meaning that they may be omitted by senders when not applicable. Some name/value pairs have default values which will be used when a value is not provided.

Names

Some names used in representations have special significance and can be relied on to be used consistently across all representations.

href

The value should be interpreted as a URI to an external resource.

self

The value should be interpreted as a URI which can be used to update or delete the JSON object containing the "self" pair.

name

The value should be interpreted as a localized, human readable name for the resource.

id

The value should be interpreted as a non-localized, non-human readable identifier for the resource.

Types

The values in representations are expected to have various types described below.

string

A JSON string.

number

A JSON number.

int

A JSON number that may not have a fractional part.

float

A JSON number that may have a fractional part.

long

An arbitrarily sized integer formatted as a decimal JSON string.

time

A JSON string containing an ISO 8601 formatted combined date and UTC time with 3 decimal places of precision.

array

A JSON array of JSON objects.

Authorization

Requests to non-public parts of the API are made on behalf of a character. Client applications are further restricted by the set of scopes a player has allowed the application to use on behalf of a character. When making a request to a non-public part of the API, client applications must supply an OAuth 2 token granted by login.eveonline.com in the Authorization header. If the character is not allowed to make the request, or the token is not have the correct scopes, the request will be denied.

Localization

Clients may specify the languages they would like to receive responses in by providing the Accept-Language header with their requests.

Example javascript client

An example Javascript client that showcases how to use CREST APIs can be found here: https://github.com/jimpurbrick/contactjs

Resources

Api

The CREST API entry point

• GET, accept vnd.ccp.eve.Api-v1

Capsuleer

Private information about a character. Requires the capsuleerRead scope to access.

• GET, accept vnd.ccp.eve.Capsuleer-v1

Character

Public character resource

• GET, accept vnd.ccp.eve.Character-v1

Contact

A contact relationship including standing and watched status. Contained within a ContactList. Character contacts require the personalContactsWrite scope to update. Corporation contacts require the corporationContactsWrite scope to update.

• DELETE, remove contact from parent ContactList
• PUT, update a contact's standing or watch list status, content vnd.ccp.eve.Contact-v1

ContactList

A Collection of Contacts. Character contacts require the personalContactsRead scope to access. Corporation contacts require the corporationContactsRead scope to access.

• GET, Get the Collection of Contacts, accept vnd.ccp.eve.ContactCollection-v1
• POST, add new Contact, content vnd.ccp.eve.Contact-v1

Corporation

• GET, accept vnd.ccp.eve.Corporation-v1

Search

A Collection of references to Resources matching the provided query. Accepts "name" as a query string parameter which is matched against resource names.

• GET, accept vnd.ccp.eve.Collection-v1

Representations

vnd.ccp.eve.Api-v1

vnd.ccp.eve.Capsuleer-v1

vnd.ccp.eve.Character-v1

vnd.ccp.eve.Collection-v1

vnd.ccp.eve.Contact-v1

vnd.ccp.eve.ContactCollection-v1

vnd.ccp.eve.Corporation-v1

vnd.ccp.eve.Reference-v1

Scopes

capsuleerRead

Read your character sheet

corporationContactsRead

Read your corporation's contact list and standings

corporationContactsWrite

Update your corporation's contact list and standings

personalContactsRead

Read your personal contact list, standings and watchlist

personalContactsWrite

Update your personal contact list, standings and watchlist