Struct screeps_api::Api

pub struct Api<C, H = Client<C>> {
    pub url: Url,
    // some fields omitted
}

API Object, stores the current API token and allows access to making requests.

Fields

url: Url

The base URL for this API instance.

Methods

impl<C, H> Api<C, H>

pub fn new(client: H) -> Self

Creates a new API instance for the official server with the https://screeps.com/api/ base url.

Use [with_url] or [set_url] to change to a custom server.

The returned instance can be used to make anonymous calls. Use [with_token] or [set_token] to enable authenticated access.

pub fn set_url<U: AsRef<str>>(&mut self, url: U) -> Result<(), ParseError>

Sets the server url this api client will use.

See also [with_url].

pub fn with_url<U: AsRef<str>>(self, url: U) -> Result<Self, ParseError>

Sets the server url this api client will use, and returns the client.

See also [set_url].

pub fn set_token<T: Into<Token>>(&mut self, token: T)

Sets the auth token this api client will use.

See also [with_token].

pub fn with_token<T: Into<Token>>(self, token: T) -> Self

Sets the auth token this api client will use, and returns the client.

See also [set_token].

pub fn token_storage(&self) -> &TokenStorage

Retrieves the token storage for this client.

impl<C: Connect + 'static, H: HyperClient<C>> Api<C, H>

pub fn login<'b, U, V>(
    &self,
    username: U,
    password: V
) -> FutureResponse<LoggedIn> where
    U: Into<Cow<'b, str>>,
    V: Into<Cow<'b, str>>, 

Logs in with the given username and password and returns a result containing the token.

Use client.set_token(logged_in.token) to let the client use the token from logging in.

pub fn register(
    &self,
    details: RegistrationDetails
) -> impl Future<Item = RegistrationSuccess, Error = Error>

Registers a new account with the given username, password and optional email and returns a result. Successful results contain no information other than that of success.

This is primarily for private servers with screepsmod-auth installed. Unknown if this works on the official server.

pub fn my_info(
    &self
) -> Result<impl Future<Item = MyInfo, Error = Error>, NoToken>

Gets user information on the user currently logged in, including username and user id.

pub fn world_start_room(
    &self
) -> Result<impl Future<Item = WorldStartRoom, Error = Error>, NoToken>

Gets the world shard and room name the server thinks the client should start with viewing.

pub fn shard_start_room<'b, U>(
    &self,
    shard: U
) -> Result<impl Future<Item = WorldStartRoom, Error = Error>, NoToken> where
    U: Into<Cow<'b, str>>, 

Gets the room name the server thinks the client should start with viewing for a particular shard.

pub fn map_stats<'a, U, V>(
    &self,
    shard: &'a str,
    rooms: &'a V
) -> Result<impl Future<Item = MapStats, Error = Error>, NoToken> where
    U: AsRef<str>,
    &'a V: IntoIterator<Item = U>, 

Get information on a number of rooms.

pub fn room_overview<'b, U, V>(
    &self,
    shard: U,
    room_name: V,
    request_interval: u32
) -> Result<impl Future<Item = RoomOverview, Error = Error>, NoToken> where
    U: Into<Cow<'b, str>>,
    V: Into<Cow<'b, str>>, 

Gets the overview of a room, returning totals for usually 3 intervals, 8, 180 and 1440, representing data for the past hour, data for the past 24 hours, and data for the past week respectively.

All Allowed request_intervals are not known, but at least 8, 180 and 1440 are allowed. The returned data, at the time of writing, includes 8 data points of each type, representing equal portions of the time period requested (hour for 8, day for 180, week for 1440).

pub fn room_terrain<'b, U, V>(
    &self,
    shard: Option<U>,
    room_name: V
) -> impl Future<Item = RoomTerrain, Error = Error> where
    U: Into<Cow<'b, str>>,
    V: Into<Cow<'b, str>>, 

Gets the terrain of a room, returning a 2d array of 50x50 points.

Does not require authentication.

pub fn shard_list(&self) -> impl Future<Item = Vec<ShardInfo>, Error = Error>

Gets a list of shards available on this server. Errors with a 404 error when connected to a non-sharded server.

Does not require authentication.

pub fn room_status<'b, U>(
    &self,
    room_name: U
) -> Result<impl Future<Item = RoomStatus, Error = Error>, NoToken> where
    U: Into<Cow<'b, str>>, 

Gets the "status" of a room: if it is open, if it is in a novice area, if it exists.

pub fn recent_pvp(
    &self,
    details: RecentPvpDetails
) -> impl Future<Item = RecentPvp, Error = Error>

Experimental endpoint to get all rooms in which PvP has recently occurred, or where PvP has occurred since a certain game tick.

pub fn leaderboard_season_list(
    &self
) -> Result<impl Future<Item = Vec<LeaderboardSeason>, Error = Error>, NoToken>

Gets a list of all past leaderboard seasons, with end dates, display names, and season ids for each season.

Seasons are a way of having limited time periods (usually one month) in which all rankings are reset at the beginning of, and points earned during the time period contribute to a player's rank in that season.

This method does not return any actual data, but rather just a list of valid past season, any of the ids of which can then be used to retrieve more information.

pub fn find_season_leaderboard_rank<'b, U, V>(
    &self,
    leaderboard_type: LeaderboardType,
    username: U,
    season: V
) -> Result<impl Future<Item = FoundUserRank, Error = Error>, NoToken> where
    U: Into<Cow<'b, str>>,
    V: Into<Cow<'b, str>>, 

Finds the rank of a user in a specific season for a specific leaderboard type.

Will return ApiError::UserNotFound when the username does not exist, and ApiError::ResultNotFound when the user exists but does not have a rank for the given season. The user will not have a rank when either the account did not exist when the season ended, or the user either processed no power or upgraded no controllers, during the specific leaderboard season.

This is technically the same API endpoint as find_leaderboard_rank, but the result format differs when requesting a specific season from when requesting all season ranks.

pub fn find_leaderboard_ranks<'b, U>(
    &self,
    leaderboard_type: LeaderboardType,
    username: U
) -> Result<impl Future<Item = Vec<FoundUserRank>, Error = Error>, NoToken> where
    U: Into<Cow<'b, str>>, 

Finds the rank of a user for all seasons for a specific leaderboard type.

This will return ApiError::UserNotFound if a username does not exist, and may also return an empty Vec as the result if the user does not have any ranks in the given leaderboard type (they have never contributed any global control points, or processed power, depending on the type).

pub fn leaderboard_page<'b, U>(
    &self,
    leaderboard_type: LeaderboardType,
    season: U,
    limit: u32,
    offset: u32
) -> Result<impl Future<Item = LeaderboardPage, Error = Error>, NoToken> where
    U: Into<Cow<'b, str>>, 

Gets a page of the leaderboard for a given season.

Limit dictates how many users will be returned, maximum is 20. Higher than that will cause an InvalidParameters error message.

Offset doesn't have to be a multiple of limit, but it's most likely most useful that it is. Offset 0 will get you the start/top of the ranked list.

Trait Implementations

impl<C, H: Clone> Clone for Api<C, H>

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<C: Debug, H: Debug> Debug for Api<C, H>

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

Formats the value using the given formatter.