#api-client #http-request #e621 #client #furry #async-client #api-bindings

rs621

Rust crate for the E621 API (a large online archive of furry art)

11 releases (6 breaking)

0.7.0-alpha1 Jun 27, 2021
0.6.0 Jan 30, 2021
0.6.0-alpha1 Jun 21, 2020
0.5.0-alpha2 Sep 17, 2019
0.3.0 Jul 27, 2019

#2257 in Web programming

Download history 12/week @ 2024-07-06 54/week @ 2024-07-27 59/week @ 2024-09-21

59 downloads per month

MIT/Apache

57KB
1K SLoC

rs621

build Crates.io Docs.rs Telegram

Rust bindings for the e621.net API.

E621 is a large online archive of furry (anthropomorphic) art. rs621 provides easy-to-use bindings to its public HTTP API. It uses the reqwest crate to make HTTPs requests and exposes an asynchronous API.

Features

  • Highly asynchronous
  • Convenient stream-based API.
  • Post listing and searching, using any of the search options from the website.
  • Pool listing and searching.
  • Unlimited result count (automatically makes more requests in sequence to go beyond the API limit of 320 posts per request).
  • Automatic rate-limit throttling.
  • Bulk-oriented API.

Usage

Note: the API is highly asynchronous. If you're not familiar with those concepts, check out Asynchronous Programming in Rust.

First, create a Client. You'll need to provide the domain URL you'd like to use, without the final slash (most likely https://e926.net or its unsafe counterpart). You also have to provide a descriptive User-Agent for your project. The official API encourages you to include your E621 username so that you may be contacted if your project causes problems.

let client = Client::new("https://e926.net", "MyProject/1.0 (by username on e621)")?;

You can now use that client to make various operations, like a basic search, with Client::post_search. The function returns a Stream, which is like an asynchronous version of Iterator.

use futures::prelude::*;

let mut post_stream = client.post_search(&["fluffy", "order:score"][..]).take(20);

while let Some(post) = post_stream.next().await {
    println!("Post #{}", post?.id);
}

If you have a list of post IDs:

let mut post_stream = client.get_posts(&[8595, 535, 2105, 1470]);

while let Some(post) = post_stream.next().await {
    println!("Post #{}", post?.id);
}

Best effort should be made to make as few API requests as possible. rs621 helps by providing bulk-oriented methods that take care of this for you. For example, if you have 400 post IDs you'd like to fetch, a single call to Client::get_posts should be enough and WILL be faster. Do NOT call it repeatedly in a loop.

Requirements

rs621 uses the rust-openssl crate. It has some requirements:

On Linux:

  • OpenSSL 1.0.1, 1.0.2, or 1.1.0 with headers (see rust-openssl).

On Windows and macOS:

  • Nothing.

See reqwest on crates.io for more details.

License

rs621 is licensed under the terms of both the MIT license and the Apache License (Version 2.0), at your choice.

See LICENSE-MIT and LICENSE-APACHE-2.0 files for the full texts.

Dependencies

~5–17MB
~248K SLoC