-
Notifications
You must be signed in to change notification settings - Fork 36
Module: EveCrest
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 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));
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);
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);
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 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));
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.
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.
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.
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()
;
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 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();
var contact = character.Query(r => r.Contacts).Items.Single(r => r.Contact.Id == 157924121);
contact.Delete();
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 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);