modio/
lib.rs

1//! Modio provides a set of building blocks for interacting with the [mod.io](https://mod.io) API.
2//!
3//! The client uses asynchronous I/O, backed by the `futures` and `tokio` crates, and requires both
4//! to be used alongside.
5//!
6//! # Authentication
7//!
8//! To access the API authentication is required and can be done via several ways:
9//!
10//! - Request an [API key (Read-only)](https://mod.io/me/access)
11//! - Manually create an [OAuth 2 Access Token (Read + Write)](https://mod.io/me/access#oauth)
12//! - [Email Authentication Flow](Client::request_token) to create an OAuth 2 Access Token
13//!   (Read + Write)
14//! - [External Authentication](Client::external_auth) to create an OAuth 2 Access Token (Read + Write)
15//!   automatically on platforms such as Steam, GOG, itch.io, Switch, Xbox, Discord and Oculus.
16//!
17//! # Rate Limiting
18//!
19//! - API keys linked to a game have **unlimited requests**.
20//! - API keys linked to a user have **60 requests per minute**.
21//! - OAuth2 user tokens are limited to **120 requests per minute**.
22//!
23//! [`Error::is_ratelimited`] will return true
24//! if the rate limit associated with credentials has been exhausted.
25//!
26//! # Example: Basic setup
27//!
28//! ```no_run
29//! use modio::Client;
30//!
31//! #[tokio::main]
32//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
33//!     let modio = Client::builder(std::env::var("MODIO_API_KEY")?).build()?;
34//!
35//!     // create some tasks and execute them
36//!     // let result = task.await?;
37//!     Ok(())
38//! }
39//! ```
40//!
41//! For testing purposes use [`Builder::host`] to create a client for the
42//! mod.io [test environment](https://docs.mod.io/restapiref/#testing).
43//!
44//! [`Builder::host`]: crate::client::Builder::host
45//!
46//! # Example: Chaining api requests
47//!
48//! ```no_run
49//! # #[tokio::main]
50//! # async fn main() -> Result<(), Box<dyn std::error::Error>> {
51//! #    let modio = modio::Client::builder(std::env::var("MODIO_API_KEY")?).build()?;
52//! use modio::types::id::Id;
53//!
54//! // OpenXcom: The X-Com Files
55//! let (game_id, mod_id) = (Id::new(51), Id::new(158));
56//! let resp = modio.get_mod(game_id, mod_id).await?;
57//! let mod_ = resp.data().await?;
58//!
59//! // Get mod with its dependencies and all files
60//! let resp = modio.get_mod_dependencies(game_id, mod_id).await?;
61//! let deps = resp.data().await?;
62//!
63//! let resp = modio.get_files(game_id, mod_id).await?;
64//! let files = resp.data().await?;
65//!
66//! println!("{}", mod_.name);
67//! println!(
68//!     "deps: {:?}",
69//!     deps.data.into_iter().map(|d| d.mod_id).collect::<Vec<_>>()
70//! );
71//! for file in files.data {
72//!     println!("file id: {} version: {:?}", file.id, file.version);
73//! }
74//! #    Ok(())
75//! # }
76//! ```
77//!
78//! # Example: Downloading mods
79//!
80//! ```no_run
81//! # #[tokio::main]
82//! # async fn main() -> Result<(), Box<dyn std::error::Error>> {
83//! #    let modio = modio::Client::builder(std::env::var("MODIO_API_KEY")?).build()?;
84//! use modio::types::id::Id;
85//! use modio::util::download::{Download, DownloadAction, ResolvePolicy};
86//!
87//! // Download the primary file of a mod.
88//! let action = DownloadAction::Primary {
89//!     game_id: Id::new(5),
90//!     mod_id: Id::new(19),
91//! };
92//! modio.download(action).save_to_file("mod.zip").await?;
93//!
94//! // Download the specific file of a mod.
95//! let action = DownloadAction::File {
96//!     game_id: Id::new(5),
97//!     mod_id: Id::new(19),
98//!     file_id: Id::new(101),
99//! };
100//! modio.download(action).save_to_file("mod.zip").await?;
101//!
102//! // Download the specific version of a mod.
103//! // if multiple files are found then the latest file is downloaded.
104//! // Set policy to `ResolvePolicy::Fail` to return with
105//! // `modio::download::Error::MultipleFilesFound` as source error.
106//! let action = DownloadAction::Version {
107//!     game_id: Id::new(5),
108//!     mod_id: Id::new(19),
109//!     version: "0.1".to_string(),
110//!     policy: ResolvePolicy::Latest,
111//! };
112//! modio.download(action).save_to_file("mod.zip").await?;
113//! #    Ok(())
114//! # }
115//! ```
116#![doc(html_root_url = "https://docs.rs/modio/0.14.0")]
117#![deny(rust_2018_idioms)]
118#![deny(rustdoc::broken_intra_doc_links)]
119#![allow(clippy::upper_case_acronyms)]
120#![allow(
121    clippy::module_name_repetitions,
122    clippy::must_use_candidate,
123    clippy::return_self_not_must_use,
124    clippy::too_many_lines
125)]
126
127pub mod client;
128pub mod request;
129pub mod response;
130pub mod types;
131pub mod util;
132
133mod error;
134
135pub use crate::client::Client;
136pub use crate::error::{Error, Result};
modio/lib.rs

modio/
lib.rs
