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
//! Wrapper crate for the [e621.net](https://e926.net) API. //! //! ## Usage //! //! Note: the API is highly asynchronous. If you're not familiar with those concepts, check out //! [Asynchronous Programming in Rust](https://rust-lang.github.io/async-book/). //! //! 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](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. //! //! ```no_run //! # use rs621::client::Client; //! # fn main() -> Result<(), rs621::error::Error> { //! let client = Client::new("https://e926.net", "MyProject/1.0 (by username on e621)")?; //! # Ok(()) } //! ``` //! //! 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`]. //! //! ```no_run //! # use rs621::client::Client; //! use futures::prelude::*; //! //! # #[tokio::main] //! # async fn main() -> Result<(), rs621::error::Error> { //! # let client = Client::new("https://e926.net", "MyProject/1.0 (by username on e621)")?; //! let mut post_stream = client.post_search(&["fluffy", "order:score"][..]).take(20); //! //! while let Some(post) = post_stream.next().await { //! println!("Post #{}", post?.id); //! } //! # Ok(()) } //! ``` //! //! If you have a list of post IDs: //! //! ```no_run //! # use rs621::client::Client; //! # use futures::prelude::*; //! # #[tokio::main] //! # async fn main() -> Result<(), rs621::error::Error> { //! # let client = Client::new("https://e926.net", "MyProject/1.0 (by username on e621)")?; //! let mut post_stream = client.get_posts(&[8595, 535, 2105, 1470]); //! //! while let Some(post) = post_stream.next().await { //! println!("Post #{}", post?.id); //! } //! # Ok(()) } //! ``` //! //! 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 //! > ```text //! > 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. //! > //! > [[...]](https://e926.net/help/show/api#basics) //! //! 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. //! //! [`Client`]: client/struct.Client.html //! [`Client::post_search`]: client/struct.Client.html#method.post_search //! [`Stream`]: https://docs.rs/futures/0.3.5/futures/stream/trait.Stream.html //! [`Iterator`]: https://doc.rust-lang.org/std/iter/trait.Iterator.html //! [`Client::get_posts`]: client/struct.Client.html#method.get_posts /// Client related structures. pub mod client; /// Error management. pub mod error; /// Post management. pub mod post; /// Pool management. pub mod pool;