Crate modio

Modio provides a set of building blocks for interacting with the mod.io API.

The client uses asynchronous I/O, backed by the futures and tokio crates, and requires both to be used alongside.

Authentication

To access the API authentication is required and can be done via several ways:

• Request an API key (Read-only)
• Manually create an OAuth 2 Access Token (Read + Write)
• Email Authentication Flow to create an OAuth 2 Access Token (Read + Write)
• External Authentication to create an OAuth 2 Access Token (Read + Write) automatically on platforms such as Steam, GOG, itch.io, Switch, Xbox, Discord and Oculus.

Rate Limiting

• API keys linked to a game have unlimited requests.
• API keys linked to a user have 60 requests per minute.
• OAuth2 user tokens are limited to 120 requests per minute.

Error::is_ratelimited will return true if the rate limit associated with credentials has been exhausted.

Example: Basic setup

use modio::{Credentials, Modio};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let modio = Modio::new(Credentials::new("user-or-game-api-key"))?;

    // create some tasks and execute them
    // let result = task.await?;
    Ok(())
}

For testing purposes use Modio::host to create a client for the mod.io test environment.

Example: Chaining api requests

use futures_util::future::try_join3;
use modio::filter::Filter;
use modio::types::id::Id;

// OpenXcom: The X-Com Files
let modref = modio.mod_(Id::new(51), Id::new(158));

// Get mod with its dependencies and all files
let deps = modref.dependencies().list();
let files = modref.files().search(Filter::default()).collect();
let mod_ = modref.get();

let (m, deps, files) = try_join3(mod_, deps, files).await?;

println!("{}", m.name);
println!(
    "deps: {:?}",
    deps.into_iter().map(|d| d.mod_id).collect::<Vec<_>>()
);
for file in files {
    println!("file id: {} version: {:?}", file.id, file.version);
}

Example: Downloading mods

use modio::download::{DownloadAction, ResolvePolicy};
use modio::types::id::Id;

// Download the primary file of a mod.
let action = DownloadAction::Primary {
    game_id: Id::new(5),
    mod_id: Id::new(19),
};
modio
    .download(action)
    .await?
    .save_to_file("mod.zip")
    .await?;

// Download the specific file of a mod.
let action = DownloadAction::File {
    game_id: Id::new(5),
    mod_id: Id::new(19),
    file_id: Id::new(101),
};
modio
    .download(action)
    .await?
    .save_to_file("mod.zip")
    .await?;

// Download the specific version of a mod.
// if multiple files are found then the latest file is downloaded.
// Set policy to `ResolvePolicy::Fail` to return with
// `modio::download::Error::MultipleFilesFound` as source error.
let action = DownloadAction::Version {
    game_id: Id::new(5),
    mod_id: Id::new(19),
    version: "0.1".to_string(),
    policy: ResolvePolicy::Latest,
};
modio
    .download(action)
    .await?
    .save_to_file("mod.zip")
    .await?;

Re-exports

• pub use crate::auth::Credentials;
• pub use crate::download::DownloadAction;
• pub use crate::types::Deletion;
• pub use crate::types::Editing;
• pub use crate::types::TargetPlatform;
• pub use crate::types::TargetPortal;

Modules

• auth
  Authentication Flow interface
• comments
  Mod comments interface
• download
  Downloading mod files.
• files
  Modfile interface
• filter
  Filtering and sorting
• games
  Games interface
• metadata
  Mod metadata KVP interface
• mods
  Mods Interface
• reports
  Reports interface
• teams
  Team members interface
• types
  Model types defining the mod.io API.
• user
  User interface

Structs

• Builder
  A Builder can be used to create a Modio client with custom configuration.
• Error
  The Errors that may occur when using Modio.
• Modio
  Endpoint interface to interacting with the mod.io API.
• Page
  A Page returned by the Query::paged stream for a search result.
• Query
  Interface for retrieving search results.

Type Aliases

• Result
  A Result alias where the Err case is modio::Error.