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.