minehut 2.0.0

Simple, easy to use Rust wrapper for the Minehut API
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107

//! This is the servers public modules to access data related to Minehut
//! servers. One of the more used modules.
//! 
//! This module provides functions for:
//! 
//! * Return all online servers using `servers::all()`.
//! * Retrun specific servers by name or ID.

use crate::http;
use crate::models::{ServerResponse, ServerData, Server, ServerListResponse};

pub use super::icons;

/// Gets a vector of `Serverdata` struct from Minehut asynchronously. Returns
/// all online servers.
/// 
/// # Example
/// 
/// ```
/// async fn print_servers() {
///     // Get all servers and print their player count
///     minehut::servers::all().await.unwrap().into_iter().for_each(|s| {
///         println!("{} players on {}", s.player_data.player_count, s.name);
///     });
/// }
/// ```
/// 
/// # Errors
/// 
/// Returns an error if Reqwest could not fetch the data or if it could not 
/// parse the JSON. This is usually a network problem.
pub async fn all() -> Result<Vec<ServerData>, crate::Error> {
    let server_list = http::req_data::<ServerListResponse>("servers").await?;

    Ok(server_list.servers)
}

/// Gets a Server struct from the specified name asynchronously. Returns all the
/// useful server information.
/// 
/// # Arguments
/// 
/// * `name` - Name of the server.
/// 
/// # Example
/// 
/// ```
/// async fn wife() -> Result<(), minehut::Error> {
///     // Get server named "Wife"
///     let server = minehut::servers::server_from_name("Wife").await;
///     
///     // Server might not exist, so we do a check
///     match server {
///         Ok(s) => println!("{}", s.player_count),
///         Err(_) => println!("Could not find server named Wife")
///     }
///     Ok(())
/// }
/// ```
/// 
/// # Errors
/// 
/// Returns `None` if the server name passed as a parameter does not link to 
/// any servers. 
pub async fn server_from_name(name: &str) -> Result<Server, crate::Error> {
    let info = http::req_data::<ServerResponse>(
        &format!("server/{name}?byName=true")
    ).await?;

    Ok(info.server)
}  

/// Gets a Server struct from the specified server ID asynchronously.
/// 
/// # Arguments
/// 
/// * `id` - ID of the server.
/// 
/// # Example
/// 
/// ```
/// use minehut::Error;
/// 
/// #[tokio::main]
/// async fn main() {
///     let server = minehut::servers::server_from_id("93nmIi2meopOs3").await;
///     
///     match server {
///         Err(e) => match e {
///             Error::Json(_) => println!("Failed to de-serialize data."),
///             Error::Http(_) => println!("HTTP problems.")
///         },
///         Ok(s) => println!("{s:?}")
///     }    
/// }
/// ```
/// # Errors
/// 
/// `servers::server_from_id(&str)` returns `Err` if the server ID passed as
/// a parameter does not link to any servers.
pub async fn server_from_id(id: &str) -> Result<Server, crate::Error> {
    let info = http::req_data::<ServerResponse>(
        &format!("server/{id}")
    ).await?;

    Ok(info.server)
}