Skip to content
Lars Kristian Dahl edited this page May 4, 2016 · 6 revisions

For more examples, please check https://github.com/ezet/evelib/blob/master/EveLib.Tests/EveCrest_Authed_Tests.cs

EveCrest supports both public and authenticated CREST.

To use public mode, simply create a new EveCrest object:

EveCrest crest = new EveCrest();

To use authenticated mode, use one of the two parameterized constructors:

EveCrest crest = new EveCrest(accessToken);
EveCrest crest = new EveCrest(refreshToken, encodedKey);

You can not change mode after creating the object. For authenticated mode, you can change the tokens and keys after creation if needed. Instances created with a refresh token have EnableAutomaticTokenRefresh enabled by default.

To request data, you will usually start by requesting the CREST root, and navigating using Query() from there:

var alliances = crest.GetRoot().Query(r => r.Alliances).

Query() and Load()

Query and Load lets you obtain data the way CREST is meant to be used, with no statically typed URIs. Most objects returned by EveCrest has a Query() method, which can be used to query additional resources. EveCrest also has a Load() method, which is used internally by Query(), and can be used the same way. Both methods access a link to a resource, or a collection of links, and will immediately request the data from CREST. By utilizing these methods you can navigate CREST from the root, by following the links to other resources. This is the preferred way to use CREST, since it will always remain in sync with the API design.

// setup
var crest = new EveCrest(refreshToken, encodedKey);
// get root object
var root = crest.GetRoot();
var regions = root.Query(r => r.Regions);
// or: var regions = crest.Load(root.Regions);
var regionData = regions.Query(regions => regions.Where(region => region.Id == 1));

You can also chain it:

var regionData = crest.GetRoot().Query(root => root.Regions).Query(regions => regions.Items); // gets all data for all regions

Or async:

var regionData = await (await (await crest.GetRootAsync()).QueryAsync(r => r.Regions)).QueryAsync(regions => regions.Take(5));

Loading Images

To load images linked from CREST, pass the ImageHref object to LoadImage available on the EveCrest object, similar to how you can pass a regular Href to Load.

var crest = new EveCrest();
byte[] imageData = crest.LoadImage(someImageHref);

Query Parameters

Some endpoints, such as Market Orders, require additional parameters. Query parameters can be passed as statically typed parameter name/value pair, or by passing a resource link. Passing resource links should be preferred.

Using resource links, the parameter name is resolved automatically:

// get the item
var item = _crest.GetRoot().Query(r => r.ItemTypes).Query(r => r.First());
// get the orders, passing our item to the final Query()
var order = _crest.GetRoot().Query(r => r.Regions).Query(r => r.Items.First()).Query(r => r.MarketOrders, item);

Using a statically typed parameter name and value pair, note that you need to specify the parameter name type in addition to the value:

var itemUrl = "https://crest-tq.eveonline.com/types/589/"
var order = _crest.GetRoot().Query(r => r.Regions).Query(r => r.Items.First()).Query(r => r.MarketOrders, "type", itemUrl);

Explicit Collection Paging

All ResourceCollections results can be paginated, and have the properties PageCount and TotalCount. Here's an example adding all MarketTypes to a list:

var types = root.Query(r => r.MarketTypes);
var list = types.Items.ToList();
while (types.Next != null)  {
    types = types.Query(t => t.Next);
    list.AddRange(types.Items);
}
// do work with list

You can also use the built in function AllItems, available on collection resources.

var types = root.Query(r => r.MarketTypes);
var list = types.AllItems();
Automatic Collection Paging on Query

Automatic Paging is enabled by default, and can be set through the EnableAutomaticPaging property. This will automatically perform additional requests for data when using any Query method to query resources, if the resource you are performing a query on has multiple pages. Examples:

EveCrest crest = new EveCrest(accessToken);
var itemGroups = crest.GetRoot().Query(r => r.ItemGroups);
var group = itemGroups.Query(r => r.Single(a => a.Id == 123));
var groups = itemGroups.Query(r => r.Where(a => a.Id > 123));

Authenticated Crest

To use authenticated CREST, you need to obtain either an Access Token or a Refresh Token and Encrypted Key. EveCrest can not acquire these tokens, and you will have to use EveAuth or some other external method. To learn more about acquiring these tokens, visit https://developers.eveonline.com/resource/single-sign-on. If you want to utilize a refresh token you also need to provide the associated Base64 encrypted key. You can provide these through their respective properties on the EveCrest object. To enable authenticated mode, set Mode to Authenticated. If you have set a RefreshToken and EncryptedKey, you can enable automatic token refreshes by setting EnableAutomaticTokenRefresh to true.

Advanced settings

There are some more advanced settings available through the RequestHandler instance on your EveCrest object. You can change things such as the serializer, number of concurrent requests, and whether to throw an exception for deprecated or unknown resoruces.

Exceptions

All calls to the CREST API can throw EveCrestException, which inherits from EveLibWebException. This additionaly exposes Message, Key, ExceptionType and RefId as returned by the API. If using automatic token refresh, or refreshing it manually, EveCrest can throw a EveAuthException. When requesting a resource that is live but not implemented yet, it will throw a ResourceNotSupportedException. If this happens, please notify a developer. If requesting a resource that isn't public yet, you will get a regular EveCrestException. If you set RequestHandler.ThrowOnDeprecated to true, you will get a DeprecatedResourceException when requesting a resource that has been marked by CCP as deprecated. This is mostly used for development.

Writable Resources

POST requests can be used to save new entities to CREST. In most cases, these requests should be initiated by getting a object through the Character resource.

var character = crest.GetRoot().Query(r => r.Decode).Query(r => r.Character);

This is the basis for the following examples.

It is possible to create writable objects using the new operator, but then you will have to set the Href and/or PostUri properties manually. The recommended method of writing to CREST is to use the Save() and Delete() methods available on the IEditableEntity objects. An alternative method is to use the EveCrest.SaveEntity(), EveCrest.AddEntity(), EveCrest.UpdateEntity() and EveCrest.DeleteEntity() methods directly. Save() attempts to use internal logic to determine whether to use AddEntity() or UpdateEntity(). You can force a request to be sent as a POST request by using .Save(true); or by using EveCrest.AddEntity();

POST

All resources that support POST requests expose a Create() method, which returns an object initialized for the specific resource.

var contact = character.Contacts.Create();

Proceed by setting the relevant properties and saving:

contact.Contact.Href = "https://crest-tq.eveonline.com/characters/157924121/";
contact.Watched = false;
contact.Standing = 5;
contact.Save();
PUT

PUT requests should generally be made on objects retrieved through CREST.

var contact = character.Query(r => r.Contacts).Items.Single(r => r.Contact.Id == 157924121);
contact.Standing = 10;
contact.Save();
DELETE
var contact = character.Query(r => r.Contacts).Items.Single(r => r.Contact.Id == 157924121);
contact.Delete();

Editing fits

The fits resource does not support editing existing fits. A simple workaround is to delete the fit before saving it, which causes Save() to perform a POST request instead of PUT.

var fit = character.Query(r => r.Fittings).Items.Single(r => r.Fitting.Name == "myfit");
fit.Delete();
fit.Name = "a better fit";
fit.Save();

OPTIONS and HEAD

OPTIONS and HEAD requests can be made by calling the respective methods on an EveCrest object, passing in a ICrestResource, ILinkable<> or Href<>.

var rootOptions = crest.QueryOptions(crest.GetRoot());
var allianceOptions = crest.QueryOptions(crest.GetRoot().Alliances);
var head = crest.QueryHead(crest.GetRoot().Incursions);