8 stable releases
1.2.0 | Oct 28, 2023 |
---|---|
1.1.1 | Jun 1, 2023 |
1.1.0 | May 15, 2023 |
1.0.4 | Apr 26, 2023 |
1.0.0 | Apr 25, 2023 |
#57 in HTTP client
39 downloads per month
81KB
1K
SLoC
topgg

The official Rust SDK for the Top.gg API.
Getting Started
Make sure to have a Top.gg API token handy. If not, then view this tutorial on how to retrieve yours. After that, add the following line to the dependencies
section of your Cargo.toml
:
topgg = "1.2"
Features
This library provides several feature flags that can be enabled/disabled in Cargo.toml
. Such as:
api
: Interacting with the Top.gg API and accessing thetop.gg/api/*
endpoints. (enabled by default)autoposter
: Automating the process of periodically posting bot statistics to the Top.gg API.
webhook
: Accessing theserde
deserializabletopgg::Vote
struct.
Examples
More things can be read in the documentation.
api
: Fetching a single Discord user from it's Discord ID
use topgg::Client;
#[tokio::main]
async fn main() {
let client = Client::new(env!("TOPGG_TOKEN").to_string());
let user = client.get_user(661200758510977084).await.unwrap();
assert_eq!(user.username, "null");
assert_eq!(user.id, 661200758510977084);
println!("{:?}", user);
}
api
: Fetching a single Discord bot from it's Discord ID
use topgg::Client;
#[tokio::main]
async fn main() {
let client = Client::new(env!("TOPGG_TOKEN").to_string());
let bot = client.get_bot(264811613708746752).await.unwrap();
assert_eq!(bot.username, "Luca");
assert_eq!(bot.discriminator, "1375");
assert_eq!(bot.id, 264811613708746752);
println!("{:?}", bot);
}
api
: Querying several Discord bots
use topgg::{Client, Query};
#[tokio::main]
async fn main() {
let client = Client::new(env!("TOPGG_TOKEN").to_string());
// inputting a string searches a bot that matches that username.
for bot in client.get_bots("shiro").await.unwrap() {
println!("{:?}", bot);
}
let query = Query::new()
.limit(250)
.skip(50)
.username("shiro")
.certified(true);
for bot in client.get_bots(query).await.unwrap() {
println!("{:?}", bot);
}
}
api
: Posting your Discord bot's statistics
use topgg::Client;
#[tokio::main]
async fn main() {
let client = Client::new(env!("TOPGG_TOKEN").to_string());
let server_count = 12345;
client
.post_stats(Stats::count_based(server_count, None))
.await
.unwrap();
}
api
: Checking if a user has voted for your Discord bot
use topgg::Client;
#[tokio::main]
async fn main() {
let client = Client::new(env!("TOPGG_TOKEN").to_string());
if client.has_voted(661200758510977084).await.unwrap() {
println!("checks out");
}
}
autoposter
: Automating the process of periodically posting your Discord bot's statistics
In your Cargo.toml
:
[dependencies]
topgg = { version = "1.2", features = ["autoposter"] }
In your code:
use core::time::Duration;
use topgg::{Client, Stats};
#[tokio::main]
async fn main() {
let client = Client::new(env!("TOPGG_TOKEN").to_string());
// creates an autoposter that posts data to Top.gg every 1800 seconds (30 minutes).
// the autopost thread will stop once it's dropped.
let autoposter = client.new_autoposter(Duration::from_secs(1800));
// ... then in some on ready/new guild event ...
let server_count = 12345;
autoposter
.feed(Stats::count_based(server_count, None))
.await;
}
actix-web
: Writing an actix-web
webhook for listening to your bot/server's vote events
In your Cargo.toml
:
[dependencies]
topgg = { version = "1.2", default-features = false, features = ["actix-web"] }
In your code:
use actix_web::{
error::{Error, ErrorUnauthorized},
get, post, App, HttpServer,
};
use std::io;
use topgg::IncomingVote;
#[get("/")]
async fn index() -> &'static str {
"Hello, World!"
}
#[post("/webhook")]
async fn webhook(vote: IncomingVote) -> Result<&'static str, Error> {
match vote.authenticate(env!("TOPGG_WEBHOOK_PASSWORD")) {
Some(vote) => {
println!("{:?}", vote);
Ok("ok")
}
_ => Err(ErrorUnauthorized("401")),
}
}
#[actix_web::main]
async fn main() -> io::Result<()> {
HttpServer::new(|| App::new().service(index).service(webhook))
.bind("127.0.0.1:8080")?
.run()
.await
}
axum
: Writing an axum
webhook for listening to your bot/server's vote events
In your Cargo.toml
:
[dependencies]
topgg = { version = "1.2", default-features = false, features = ["axum"] }
In your code:
use axum::{routing::get, Router, Server};
use std::{net::SocketAddr, sync::Arc};
use topgg::{Vote, VoteHandler};
struct MyVoteHandler {}
#[axum::async_trait]
impl VoteHandler for MyVoteHandler {
async fn voted(&self, vote: Vote) {
println!("{:?}", vote);
}
}
async fn index() -> &'static str {
"Hello, World!"
}
#[tokio::main]
async fn main() {
let state = Arc::new(MyVoteHandler {});
let app = Router::new().route("/", get(index)).nest(
"/webhook",
topgg::axum::webhook(env!("TOPGG_WEBHOOK_PASSWORD").to_string(), Arc::clone(&state)),
);
let addr: SocketAddr = "127.0.0.1:8080".parse().unwrap();
Server::bind(&addr)
.serve(app.into_make_service())
.await
.unwrap();
}
rocket
: Writing a rocket
webhook for listening to your bot/server's vote events
In your Cargo.toml
:
[dependencies]
topgg = { version = "1.2", default-features = false, features = ["rocket"] }
In your code:
#![feature(decl_macro)]
use rocket::{get, http::Status, post, routes};
use topgg::IncomingVote;
#[get("/")]
fn index() -> &'static str {
"Hello, World!"
}
#[post("/webhook", data = "<vote>")]
fn webhook(vote: IncomingVote) -> Status {
match vote.authenticate(env!("TOPGG_WEBHOOK_PASSWORD")) {
Some(vote) => {
println!("{:?}", vote);
Status::Ok
},
_ => {
println!("found an unauthorized attacker.");
Status::Unauthorized
}
}
}
fn main() {
rocket::ignite()
.mount("/", routes![index, webhook])
.launch();
}
warp
: Writing a warp
webhook for listening to your bot/server's vote events
In your Cargo.toml
:
[dependencies]
topgg = { version = "1.2", default-features = false, features = ["warp"] }
In your code:
use std::{net::SocketAddr, sync::Arc};
use topgg::{Vote, VoteHandler};
use warp::Filter;
struct MyVoteHandler {}
#[async_trait::async_trait]
impl VoteHandler for MyVoteHandler {
async fn voted(&self, vote: Vote) {
println!("{:?}", vote);
}
}
#[tokio::main]
async fn main() {
let state = Arc::new(MyVoteHandler {});
// POST /webhook
let webhook = topgg::warp::webhook(
"webhook",
env!("TOPGG_WEBHOOK_PASSWORD").to_string(),
Arc::clone(&state),
);
let routes = warp::get().map(|| "Hello, World!").or(webhook);
let addr: SocketAddr = "127.0.0.1:8080".parse().unwrap();
warp::serve(routes).run(addr).await
}
Dependencies
~0.5–15MB
~212K SLoC