mangadex-api
Important
This git repo is just a fork from gondolyr/mangadex-api but the project and crate has been yanked so I will now maintain this crate for special-eureka and eureka-manager
The mangadex-api crate provides a convenient, high-level wrapper
client for the MangaDex API,
written in Rust.
It covers all public endpoints covered by their documentation.
Documentation (Old repo main branch)
Please note that as MangaDex is still in beta, this SDK will be subject to sudden breaking changes (a lot).
Disclaimer
mangadex-api is not affiliated with MangaDex.
Table of Contents
- mangadex-api
- Important
- Disclaimer
- Table of Contents
- Workspace details
- Requirements
- How to install
- Dependency Justification
- Features
- HTTP Client
- Response Structs
- Getting Started
- Using a custom reqwest Client
- Searching manga by title
- Searching manga by title with reference expansion
- Downloading chapter pages
- Using the old way
- Downloading a manga's main cover image
- Authentification (via the
oauthfeature) - License
- Contributing
Workspace details
mangadex-apiis the SDK itselfmangadex-api-typesis the crate containing all enums, and static data. Those arenon_exhaustiveby defaultmangadex-api-schemacontains all the response structs required. These support serialization with theserializefeaturemangadex-api-inputs-typescontains input types for endpoint. Please note that this input crate only contain those with multiple parameters.
Requirements
How to install
Add mangadex-api to your dependencies:
[]
# ...
# Types and schemas are always required
= "1"
= "1"
= "4"
If you are using cargo-edit, run
Dependency Justification
| Dependency | Used for | Included |
|---|---|---|
anyhow |
Capturing unexpected errors. | always |
mangadex-api-types-rust |
Enums and static data for Mangadex API | always |
mangadex-api-schema-rust |
Types used for Mangadex API | always |
clap |
Examples demonstrating the library's capabilities | dev builds |
derive_builder |
Conveniently generating setters for the API endpoint builders. | always |
fake |
Generating random data for unit tests. | dev builds |
reqwest |
Making HTTP requests to the MangaDex API. | always |
serde |
Se/dese/rializing HTTP response bodies into structs. | always |
serde_json |
Creating JSON objects for unit tests. | dev builds |
serde_qs |
Query string serialization for HTTP requests. | always |
thiserror |
Customized error handling. | always |
time |
Convenience types for handing time fields. | always |
tokio |
Async RwLock support |
sync feature only |
url |
Convenient Url type for validating and containing URLs. |
always |
uuid |
Convenient Uuid type for validating and containing UUIDs for requests and responses. Also used to randomly generate UUIDs for testing. |
always |
wiremock |
HTTP mocking to test the MangaDex API. | dev builds |
Features
All features are not included by default. To enable them, add any of the following to your project's Cargo.toml file.
-
utilsEnable the usage of the
MangaDexClient::download(). Allows you to download chapters or covers image without tears and long code. -
oauth(Enabled by default)Enable the use of the brand new OAuth 2.0 login introduced in MangaDex API 5.9.0.
Quick Note: This
oauthfeature use the personal-client approach which means that you need to register a personal client and wait that it'll be validated. More details here -
custom_list_v2: Enable the usage of the upcoming custom list system. Please note that these endpoints are deployed yet onapi.mangadex.orgbut you can use them onapi.mangadex.dev(their live dev API). For more information, please refer toFollows/CustomList API Changelog - BREAKING CHANGESon the MangaDex Forums
For example, to enable the utils feature, add the following to your Cargo.toml file:
= { = "4", = ["utils"] }
HTTP Client
The mangadex_api::MangaDexClient is asynchronous, using
reqwest as the HTTP client.
Response Structs
The response structs can be found in the mangadex-api-schema-rust crate and contain the fields in a JSON response.
Getting Started
This example demonstrates how to fetch a random manga.
use MangaDexClient;
async
This example demonstates how to fetch the Mangadex Popular Titles
use MangaDexClient;
use RelatedAttributes;
use ;
use ;
use Url;
async
Using a custom reqwest Client
By default, mangadex_api::MangaDexClient will use the default
reqwest::Client settings.
You may provide your own reqwest::Client to customize options such as the
request timeout.
use Client;
use MangaDexClient;
# async
Searching manga by title
Reference: https://api.mangadex.org/swagger.html#/Manga/get-search-manga
use MangaDexClient;
async
Searching manga by title with reference expansion
Every fetch will include all relationships but with minimal information such as the relationship type and ID. Reference expansion will include the full JSON object in the results for the types that are added to the request.
In the example below, any associated authors in the list of relationships will provide detailed information such as the author's name, biography, and website in the results.
References:
- https://api.mangadex.org/docs/01-concepts/reference-expansion/
- Endpoint: https://api.mangadex.org/docs/swagger.html#/Manga/get-search-manga
- Author object: https://api.mangadex.org/docs/swagger.html#/Author/get-author-id
use RelatedAttributes;
use MangaDexClient;
// use mangadex_api_types_rust::{ReferenceExpansionResource, RelationshipType};
use ;
async
Downloading chapter pages
Reference: https://api.mangadex.org/docs/reading-chapter/
Using the old way
// Imports used for downloading the pages to a file.
// They are not used because we're just printing the raw bytes.
// use std::fs::File;
// use std::io::Write;
use Uuid;
use MangaDexClient;
async
Using the utils feature
Via (filename, Result<bytes>) vector based
Not recommended if you want to handle each response error
use Result;
use ;
/// used for file exporting
use ;
/// It's from this manga called [`The Grim Reaper Falls In Love With A Human`](https://mangadex.org/title/be2efc56-1669-4e42-9f27-3bd232bca8ea/the-grim-reaper-falls-in-love-with-a-human)
///
/// [Chapter 1 English](https://mangadex.org/chapter/2b4e39a5-fba0-4055-a176-8b7e19faacdb) by [`Kredim`](https://mangadex.org/group/0b870e54-c75f-4d2e-8068-c40f939135fd/kredim)
async
Via tokio-stream
With tokio-stream, you can handle each response result
Without checker
use Result;
use ;
use ;
use pin;
use StreamExt;
/// It's from this manga called [`Keiken Zumi na Kimi to, Keiken Zero na Ore ga, Otsukiai Suru Hanashi`](https://mangadex.org/title/1c8f0358-d663-4d60-8590-b5e82890a1e3/keiken-zumi-na-kimi-to-keiken-zero-na-ore-ga-otsukiai-suru-hanashi)
///
/// [Chapter 13 English](https://mangadex.org/chapter/250f091f-4166-4831-9f45-89ff54bf433b) by [`Galaxy Degen Scans`](https://mangadex.org/group/ab24085f-b16c-4029-8c05-38fe16592a85/galaxy-degen-scans)
async
with checker
The checker is a function called after the response fetching but before retreiving the byte content. Example :
/// Some code here
let download = client
.download
.chapter
.mode
.report
.build?;
let chapter_files = download
.download_stream_with_checker
.await?;
/// Some code here too
Real example :
The checker will check return true if a file with the response content length has been created
use Result;
use ;
use ;
use pin;
use StreamExt;
/// It's from this manga called [`Keiken Zumi na Kimi to, Keiken Zero na Ore ga, Otsukiai Suru Hanashi`](https://mangadex.org/title/1c8f0358-d663-4d60-8590-b5e82890a1e3/keiken-zumi-na-kimi-to-keiken-zero-na-ore-ga-otsukiai-suru-hanashi)
///
/// [Chapter 13 English](https://mangadex.org/chapter/250f091f-4166-4831-9f45-89ff54bf433b) by [`Galaxy Degen Scans`](https://mangadex.org/group/ab24085f-b16c-4029-8c05-38fe16592a85/galaxy-degen-scans)
async
Downloading a manga's main cover image
Use the legacy way
While this example could directly get the cover information by passing in the cover ID, it is not often that one would have the ID off-hand, so the most common method would be from a manga result.
If you want to get all of a manga's cover images, you will need to use the cover list endpoint
and use the manga[] query parameter.
// Imports used for downloading the cover to a file.
// They are not used because we're just printing the raw bytes.
// use std::fs::File;
// use std::io::Write;
use Url;
use Uuid;
use MangaDexClient;
use CDN_URL;
// use mangadex_api_types_rust::RelationshipType;
use RelationshipType;
async
Using the utils feature (recommended)
via a cover id
use Result;
use Uuid;
use crateMangaDexClient;
use ;
/// Download the volume 2 cover of [Lycoris Recoil](https://mangadex.org/title/9c21fbcd-e22e-4e6d-8258-7d580df9fc45/lycoris-recoil)
async
via a manga id
use Result;
use MangaDexClient;
use ;
use Uuid;
/// Download the [Kimi tte Watashi no Koto Suki Nandesho?](https://mangadex.org/title/f75c2845-0241-4e69-87c7-b93575b532dd/kimi-tte-watashi-no-koto-suki-nandesho) cover
///
/// For test... of course :3
async
Authentification (via the oauth feature)
Before paste copying uhm,... touching the example code below, I recommend that you read the Mangadex Authentification Section
First, register a personal client at Mangadex Profile Settings, and wait until it's approved by staff. It can take 2 or 3 three days for now so just wait :> (it should normally be auto-approved).
After a long time, you can now login via the oauth feature.
Login
use MangaDexClient;
use ClientInfo;
use ;
async
Resfresh your token
You just call mangadex_api::MangaDexClient::oauth().refresh()
...
client
.oauth
.refresh
.send
.await?;
...
Example:
use MangaDexClient;
// use mangadex_api_schema_rust::v5::oauth::ClientInfo;
// use mangadex_api_types_rust::{Password, Username};
use ClientInfo;
use ;
use ;
async
License
Licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
Contributing
We welcome contributions from everyone. There are many ways to contribute and the CONTRIBUTING.md document explains how you can contribute and get started.