Crate rs621[−][src]
Expand description
Wrapper crate for the e621.net 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.
Notes from the official API:
User Agents
A non-empty User-Agent header is required for all requests. Please pick a descriptive User-Agent for your project. You are encouraged to include your e621 username so that you may be contacted if your project causes problems. DO NOT impersonate a browser user agent, as this will get you blocked. An example user-agent would be
MyProject/1.0 (by username on e621)
Due to frequent abuse, default user agents for programming languages and libraries are usually blocked. Please make sure that you are defining a user agent that is in line with our policy.
Thus, rs621
doesn’t have a default user agent and you are required to specify your own.
Rate Limiting
E621/E926 have a hard rate limit of two requests per second. This is a hard upper limit and if you are hitting it, you are already going way too fast. Hitting the rate limit will result in a 503 HTTP response code. You should make a best effort not to make more than one request per second over a sustained period.
rs621
will enforce this limit with a short sleeping time after every API request being made.
Modules
client | Client related structures. |
error | Error management. |
pool | Pool management. |
post | Post management. |