https://github.com/halcyonnouveau/roux
Simple and (a)synchronous Reddit API wrapper for Rust.
https://github.com/halcyonnouveau/roux
api-wrapper reddit reddit-api rust wrapper
Last synced: 2 months ago
JSON representation
Simple and (a)synchronous Reddit API wrapper for Rust.
- Host: GitHub
- URL: https://github.com/halcyonnouveau/roux
- Owner: halcyonnouveau
- License: mit
- Created: 2019-07-13T08:21:37.000Z (almost 7 years ago)
- Default Branch: main
- Last Pushed: 2026-01-05T12:02:31.000Z (5 months ago)
- Last Synced: 2026-01-20T13:58:43.912Z (5 months ago)
- Topics: api-wrapper, reddit, reddit-api, rust, wrapper
- Language: Rust
- Homepage: https://crates.io/crates/roux
- Size: 337 KB
- Stars: 108
- Watchers: 2
- Forks: 45
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Roux
[](https://github.com/halcyonnouveau/roux/actions/workflows/main.yml)
[](https://docs.rs/roux)
[](https://crates.io/crates/roux)
Roux is a simple, (a)synchronous Reddit API wrapper implemented in Rust.
## Usage
### Using OAuth
To create an OAuth client with the Reddit API, use the `Reddit` class.
```rust
use roux::Reddit;
let client = Reddit::new("USER_AGENT", "CLIENT_ID", "CLIENT_SECRET")
.username("USERNAME")
.password("PASSWORD")
.login()
.await;
let me = client.unwrap();
```
It is important that you pick a good user agent. The ideal format is `platform:program:version (by /u/yourname)`, e.g. `macos:roux:v2.0.0 (by /u/beanpup_py)`. This will authticate you as the user given in the username function.
### Usage
Using the OAuth client, you can:
#### Submit A Text Post
```rust
use roux::Reddit;
let client = Reddit::new("USER_AGENT", "CLIENT_ID", "CLIENT_SECRET")
.username("USERNAME")
.password("PASSWORD")
.login()
.await;
let me = client.unwrap();
me.submit_text("TEXT_TITLE", "TEXT_BODY", "SUBREDDIT").await?;
```
#### Submit A Link Post
```rust
use roux::Reddit;
let client = Reddit::new("USER_AGENT", "CLIENT_ID", "CLIENT_SECRET")
.username("USERNAME")
.password("PASSWORD")
.login()
.await;
let me = client.unwrap();
me.submit_link("LINK_TITLE", "LINK", "SUBREDDIT").await?;
```
### Read-Only Modules
There are also read-only modules that don't need authentication:
- [Subreddits](https://docs.rs/roux/latest/roux/subreddit/index.html)
- [Users](https://docs.rs/roux/latest/roux/user/index.html)
## Blocking Client
You can use a blocking (synchronous) API instead of tokio by enabling the `blocking` feature.
```toml
[dependencies]
roux = { version = "2", features = ["blocking"] }
```
```rust
use roux::Reddit;
let client = Reddit::new("USER_AGENT", "CLIENT_ID", "CLIENT_SECRET")
.username("USERNAME")
.password("PASSWORD")
.login();
let me = client.unwrap();
me.submit_link("LINK_TITLE", "LINK", "SUBREDDIT");
```
## 3rd-Party Libraries
- [`roux-stream`](https://github.com/torfsen/roux-stream) provides an API for continuously streaming new submissions and comments
## Contributing
Roux is not in active development but is still being maintained and currently covers the most common and useful endpoints. If you see something missing or encounter a bug, feel free to open an issue or create a pull request.
## License
Roux is licensed under the MIT license (see [LICENSE file](/LICENSE)).