Struct Esi 

pub struct Esi {
    pub access_token: Option<String>,
    pub access_expiration: Option<i64>,
    pub refresh_token: Option<String>,
    /* private fields */
}

Struct to interact with ESI.

Construct an instance of this struct using EsiBuilder.

Example

use esi_openapi::prelude::EsiBuilder;
// the struct must be mutable for some functionality
let mut esi = EsiBuilder::new()
    .user_agent("some user agent")
    .client_id("your_client_id")
    .client_secret("your_client_secret")
    .callback_url("your_callback_url")
    .build()
    .unwrap();

Fields

access_token: Option<String>

The access token from ESI, if set.

access_expiration: Option<i64>

The millisecond unix timestamp after which the access token expires, if present.

refresh_token: Option<String>

The refresh token from ESI, if set.

Implementations

impl Esi

pub async fn update_spec(&mut self) -> EsiResult<()>

Get the OpenAPI spec from ESI and store it in this struct.

The spec is requested with this struct’s compatibility date (X-Compatibility-Date), so the paths match the API version that later requests will use.

If you are making use of the try_get_endpoint_for_op_id, then this function will be called there when needed (which should only really be when the struct is constructed unless the struct is kept in memory for a very long time). When using get_endpoint_for_op_id however, you are responsible for calling this function beforehand.

Example

esi.update_spec().await.unwrap();

This always makes a request. If the spec was downloaded before with the same compatibility date and the server gave it an ETag or Last-Modified, the request is conditional (If-None-Match / If-Modified-Since) and a 304 Not Modified keeps the spec in memory instead of downloading it again. To skip the request while the spec is still fresh, use Esi::ensure_spec_fresh.

pub async fn ensure_spec_fresh(&mut self) -> EsiResult<()>

Make sure the spec is loaded and still fresh, requesting it only if it is not: it has not been downloaded by this struct (a spec given to the builder has no known age), it was downloaded with another compatibility date, or its Cache-Control: max-age has passed. Use it before a long run of calls instead of Esi::update_spec to avoid needless downloads.

pub fn get_authorize_url(&self) -> EsiResult<AuthenticationInformation>

Generate and return the URL required for the user to grant you an auth code, as wells as infos for future authentication request.

You can inspect the URL returned by ESI to your web service to ensure it matches. No checking is done by esi-openapi.

Example

let auth_info = esi.get_authorize_url().unwrap();
// then send your user to that URL
let url = auth_info.authorization_url;

If you opted to not include client information in the EsiBuilder flow, then this function will return an error instead.

pub async fn authenticate( &mut self, code: &str, pkce_verifier: Option<PkceVerifier>, ) -> EsiResult<Option<TokenClaims>>

Authenticate with ESI, exchanging a code from the authorize flow for an access token that is used to make authenticated calls to ESI.

Note that this is one of the functions that requires the struct be mutable, as the struct mutates to include the resulting access token.

If the “validate_jwt” feature is enabled (by default), then the access token’s claims will be returned. If the feature is not enabled, then the returned value will be None.

Example (client secret)

let claims = esi.authenticate("abcdef...", None).await.unwrap();

Example (PKCE/Application authentication)

 async fn run() {

pub async fn use_refresh_token(&mut self, refresh_token: &str) -> EsiResult<()>

Authenticate via a previously-fetched refresh token.

The functionality of a refresh token allows re-authenticating this struct instance without prompting the user to log into EVE SSO again. When the user is authenticated in that manner, a refresh token is returned and available via the refresh_token struct field. Store this securely should you wish to later make authenticate calls for that user.

Example

esi.use_refresh_token("abcdef...").await.unwrap();

pub async fn refresh_access_token( &mut self, refresh_token: Option<&str>, ) -> EsiResult<()>

Authenticate via a refresh token given as input, or using the internal refresh_token if it’s available.

The functionality of a refresh token allows re-authenticating this struct instance without prompting the user to log into EVE SSO again. When the user is authenticated in that manner, a refresh token is returned and available via the refresh_token struct field. Store this securely should you wish to later make authenticate calls for that user.

Example with internal token

esi.refresh_access_token(None).await.unwrap();

Example with input token

esi.refresh_access_token(Some("MyRefreshToken")).await.unwrap();

pub async fn query<T: DeserializeOwned>( &self, method: &str, request_type: RequestType, endpoint: &str, query: Option<&[(&str, &str)]>, body: Option<&str>, ) -> EsiResult<T>

Make a request to ESI.

This is mainly used as the underlying function for this library when making calls to ESI; the other functions that you should primarily be using contain more functionality, including matching endpoint with deserialization struct, evaluating & replacing URL parameters, etc.

In the event that there is not a wrapper function for the endpoint that you want to use, you can use this function to make an API call without waiting for the library to be updated.

Example

#[derive(Deserialize)]
struct ReturnedData {}
let data: ReturnedData = esi.query("GET", RequestType::Public, "abc", None, None).await.unwrap();

pub async fn query_with_pages<T: DeserializeOwned>( &self, method: &str, request_type: RequestType, endpoint: &str, query: Option<&[(&str, &str)]>, ) -> EsiResult<(T, Option<i64>)>

Like Esi::query, but also returns the total number of pages reported by the X-Pages response header, if present.

Example

let (data, pages): (Vec<serde_json::Value>, Option<i64>) = esi
    .query_with_pages("GET", RequestType::Public, "some/path", Some(&[("page", "2")]))
    .await
    .unwrap();

pub async fn fetch_all_pages<T: DeserializeOwned>( &self, request_type: RequestType, endpoint: &str, query: Option<&[(&str, &str)]>, max_pages: Option<i64>, ) -> EsiResult<Vec<T>>

Fetch every page of an endpoint paginated with the page query parameter and return the items of all pages, in order.

The first page is requested with page=1; the X-Pages header of its response says how many pages follow, and those are requested concurrently, EsiBuilder::page_concurrency at a time. Pass the other query parameters of the endpoint in query, without page. max_pages limits how many pages are fetched (None for all of them).

pub async fn post_chunked<B: Serialize, T: DeserializeOwned>( &self, request_type: RequestType, endpoint: &str, items: &[B], chunk_size: usize, ) -> EsiResult<Vec<T>>

Send a POST whose body is a JSON array and return the answers joined in order, splitting items into requests of at most chunk_size items.

Use it for endpoints that cap the length of the array (such as characters/affiliation, at 1000 ids). The chunks are sent concurrently, EsiBuilder::page_concurrency at a time. The answer to each chunk must be an array; an empty items sends no request and returns an empty list. Duplicates are not removed, and the spec asks for unique items on most of these endpoints.

pub async fn fetch_all_cursor<T: DeserializeOwned>( &self, request_type: RequestType, endpoint: &str, query: Option<&[(&str, &str)]>, items_key: &str, max_pages: Option<i64>, ) -> EsiResult<Vec<T>>

Fetch every page of an endpoint paginated with cursors (x-pagination: cursor) and return the items of all pages, in order.

items_key is the name of the array in the response that holds the records, such as "projects" or "listings". The walk follows the cursor.after value of each response until a page has no records or no further cursor. Pass the other query parameters of the endpoint (such as limit) in query, without after or before. Unless query has a limit, the maximum the spec allows (100, against a default of 10) is requested to need fewer calls. max_pages limits how many pages are fetched (None for all of them).

pub async fn cache_len(&self) -> usize

The number of responses held by the cache (0 when it is disabled).

pub async fn cache_bytes(&self) -> usize

The approximate size in bytes of the responses held by the cache (0 when it is disabled). See EsiBuilder::cache_max_bytes.

pub async fn try_get_endpoint_for_op_id( &mut self, op_id: &str, ) -> EsiResult<String>

Resolve an operationId to a URL path utilizing the OpenAPI spec.

Operation IDs are those of the ESI OpenAPI spec, e.g. GetMarketsRegionIdOrders. rfesi’s legacy snake_case IDs (e.g. get_markets_region_id_orders) are still accepted with a deprecation warning until 0.2.0.

If the spec has not yet been retrieved when calling this function, an API call will be made to ESI to fetch that data (thus the async signature of this function). If you don’t need that help (by explicitly making a call to update_spec prior) then you can use the get_endpoint_for_op_id function, which is synchronous.

Note that when making use of this function along with query, you are responsible for resolving any/all URL parameters that the endpoint may contain.

Example

let endpoint = esi
    .try_get_endpoint_for_op_id("GetAlliancesAllianceIdContactsLabels")
    .await
    .unwrap();

pub fn get_endpoint_for_op_id(&self, op_id: &str) -> EsiResult<String>

Resolve an operationId to a URL path utilizing the OpenAPI spec.

Operation IDs are those of the ESI OpenAPI spec, e.g. GetMarketsRegionIdOrders. rfesi’s legacy snake_case IDs (e.g. get_markets_region_id_orders) are still accepted with a deprecation warning until 0.2.0.

If the spec has not yet been retrieved when calling this function, this function will return an error.

Note that when making use of this function along with query, you are responsible for resolving any/all URL parameters that the endpoint may contain.

Example

let endpoint = esi.get_endpoint_for_op_id("GetAlliancesAllianceIdContactsLabels").unwrap();

pub fn required_scopes(&self, op_id: &str) -> EsiResult<Vec<String>>

The OAuth2 scopes an operation needs, from the spec. Public operations need none.

pub fn missing_scopes( &self, op_id: &str, granted: &str, ) -> EsiResult<Vec<String>>

The scopes an operation needs that are not in granted, a space-separated scope list such as the scope value of a token. Use it to fail early instead of making a request ESI will answer with 401.

pub fn required_roles(&self, op_id: &str) -> EsiResult<Vec<String>>

The corporation roles of which the character needs at least one for an operation (empty when it needs none).

pub fn declared_rate_limits(&self) -> EsiResult<HashMap<String, SpecRateLimit>>

The rate limit each route group declares in the spec, keyed by group.

These are the budgets before any response arrives; Esi::rate_limit_status has the live values once ESI has answered for a group.

pub async fn rate_limit_status(&self, group: &str) -> Option<RateLimitStatus>

Latest rate-limit status ESI reported for a route group (the X-Ratelimit-Group header value, e.g. market).

Returns None if no response from that group has been seen yet. Routes not yet moved to ESI’s rate limiter do not send these headers; they are covered by Esi::is_error_limited instead.

pub async fn rate_limit_statuses(&self) -> HashMap<String, RateLimitStatus>

Latest rate-limit status for every route group seen so far.

pub async fn is_error_limited(&self) -> Result<ErrorLimitStatus, EsiError>

Returns whether we have temporarily encountered the error limit due to too many failed responses.

If this returns true, then this client will refuse to process further requests.

pub fn get_spec(&self) -> Option<&Spec>

Retrieve this struct’s OpenAPI specification.

Use in tandem with EsiBuilder::spec.

pub fn group_access_list(&self) -> AccessListGroup<'_>

Call endpoints under the “Access List” group in ESI.

pub fn group_activities(&self) -> ActivitiesGroup<'_>

Call endpoints under the “Activities” group in ESI.

pub fn group_alliance(&self) -> AllianceGroup<'_>

Call endpoints under the “alliance” group in ESI.

pub fn group_assets(&self) -> AssetsGroup<'_>

Call endpoints under the “Assets” group in ESI.

pub fn group_bookmarks(&self) -> BookmarksGroup<'_>

Call endpoints under the “Bookmarks” group in ESI.

pub fn group_calendar(&self) -> CalendarGroup<'_>

Call endpoints under the “Calendar” group in ESI.

pub fn group_character(&self) -> CharacterGroup<'_>

Call endpoints under the “Character” group in ESI.

pub fn group_clones(&self) -> ClonesGroup<'_>

Call endpoints under the “Clones” group in ESI.

pub fn group_contacts(&self) -> ContactsGroup<'_>

Call endpoints under the “Contacts” group in ESI.

pub fn group_contracts(&self) -> ContractsGroup<'_>

Call endpoints under the “Contracts” group in ESI.

pub fn group_corporation(&self) -> CorporationGroup<'_>

Call endpoints under the “Corporation” group in ESI.

pub fn group_corporation_projects(&self) -> CorporationProjectsGroup<'_>

Call endpoints under the “Corporation Projects” group in ESI.

pub fn group_dogma(&self) -> DogmaGroup<'_>

Call endpoints under the “Dogma” group in ESI.

pub fn group_faction_warfare(&self) -> FactionWarfareGroup<'_>

Call endpoints under the “FactionWarfare” group in ESI.

pub fn group_fittings(&self) -> FittingsGroup<'_>

Call endpoints under the “Fittings” group in ESI.

pub fn group_fleets(&self) -> FleetsGroup<'_>

Call endpoints under the “Fleets” group in ESI.

pub fn group_incursions(&self) -> IncursionsGroup<'_>

Call endpoints under the “Incursions” group in ESI.

pub fn group_industry(&self) -> IndustryGroup<'_>

Call endpoints under the “Industry” group in ESI.

pub fn group_insurance(&self) -> InsuranceGroup<'_>

Call endpoints under the “Insurance” group in ESI.

pub fn group_killmails(&self) -> KillmailsGroup<'_>

Call endpoints under the “Killmails” group in ESI.

pub fn group_location(&self) -> LocationGroup<'_>

Call endpoints under the “Location” group in ESI.

pub fn group_loyalty(&self) -> LoyaltyGroup<'_>

Call endpoints under the “Loyalty” group in ESI.

pub fn group_mail(&self) -> MailGroup<'_>

Call endpoints under the “Mail” group in ESI.

pub fn group_market(&self) -> MarketGroup<'_>

Call endpoints under the “Market” group in ESI.

pub fn group_opportunities(&self) -> OpportunitiesGroup<'_>

Call endpoints under the “Opportunities” group in ESI.

pub fn group_planetary_interaction(&self) -> PlanetaryInteractionGroup<'_>

Call endpoints under the “PlanetaryInteraction” group in ESI.

pub fn group_routes(&self) -> RoutesGroup<'_>

Call endpoints under the “Routes” group in ESI.

pub fn group_cosmetics(&self) -> CosmeticsGroup<'_>

Call endpoints under the “Cosmetics” group in ESI.

pub fn group_paragon_hub(&self) -> ParagonHubGroup<'_>

Call endpoints under the “Paragon Hub” group in ESI.

pub fn group_freelance_jobs(&self) -> FreelanceJobsGroup<'_>

Call endpoints under the “Freelance Jobs” group in ESI.

pub fn group_military_campaigns(&self) -> MilitaryCampaignsGroup<'_>

Call endpoints under the “Military Campaigns” group in ESI.

pub fn group_meta(&self) -> MetaGroup<'_>

Call endpoints under the “Meta” group in ESI.

pub fn group_search(&self) -> SearchGroup<'_>

Call endpoints under the “Search” group in ESI.

pub fn group_skills(&self) -> SkillsGroup<'_>

Call endpoints under the “Skills” group in ESI.

pub fn group_sovereignty(&self) -> SovereigntyGroup<'_>

Call endpoints under the “Sovereignty” group in ESI.

pub fn group_structures(&self) -> StructuresGroup<'_>

Call endpoints under the “Structures” group in ESI.

pub fn group_status(&self) -> StatusGroup<'_>

Call endpoints under the “Status” group in ESI.

pub fn group_universe(&self) -> UniverseGroup<'_>

Call endpoints under the “Universe” group in ESI.

pub fn group_user_interface(&self) -> UserInterfaceGroup<'_>

Call endpoints under the “UserInterface” group in ESI.

pub fn group_wallet(&self) -> WalletGroup<'_>

Call endpoints under the “Wallet” group in ESI.

pub fn group_wars(&self) -> WarsGroup<'_>

Call endpoints under the “Wars” group in ESI.

Trait Implementations

impl Clone for Esi

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Esi

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.