New Plugin API

[browningluke]

Requirements

• Since the plan is to migrate the built-in MangaDex downloader to a plugin, the new API should support most/all variables currently supported by the Rename Rules.
• Should be mostly backwards compatible with the current plugins.
• Should return metadata that can (in future) be imported into series & chapters. #175

---

Below is what I've drafted. Let me know if the number of variables seems right and if any other changes need to be made. I've written a description as to what they are for / rationale for adding them.

---

getSeries(query)

The function is called by Mango when the user searches something on the plugin download page (/download/plugins), and query is a string containing the user's input.

The function should return a JSON stringified object with all of the following required variables and any of the optional ones.

Series

variable	description	required
id	Associates a returned manga with one in the library.	YES
title	The manga's title.	YES
description	A summary of the returned manga.	NO
author	The manga's author. (possibly a list for multiple authors)	NO
cover_url	URL linking to the manga's cover image.	NO
genres	List of genres (tags). (can be imported into library)	NO
chapters	List of chapters downloadable.	YES

Chapter

variable	description	required
id	ID of the chapter.	YES
title	Title of the chapter.	YES
volume	Volume number of the chapter. (e.g. Vol. 5)	NO
chapter	Chapter number of the chapter. (e.g. Ch. 35)	NO
group	Groups who produced the chapter.	NO
lang_code	Language code of chapter (e.g en)	NO
language	Language of the chapter. (e.g. English)	NO
pages	Number of pages in this chapter.	NO
tags	List containing the tags for the chapter. #175	NO

Example:

{
	id: "bisquedoll",	  
	title: "Sono Bisque Doll wa Koi o suru", 		 
	description: "<Long description goes here>", 
	author: "Shinichi Fukuda",		  
	cover_url: "https://images.catmanga.org/series/bisquedoll/covers/06.jpg",	 
	genres: [		  
		"Comedy",
		"Romance",
		...
	],
	status: "Ongoing",		  
	
	chapters: [{
		id: "bisquedoll_ch53",
		title: "Chapter 53",
		
		volume: 5,
		chapter: 53,
		group: "Tonikaku Scans",
		lang_code: "en",
		language: "English",
		pages: 13,
		
		tags: [
			"xxx",
			"xxx",
			...
		]
	},
	...
	]
}

When a user searches for a manga, the returned metadata is displayed on the download UI.

• If the series already exists in the library, the chapter will download as normal and added to the series with the correct id.
• If the series does not exist, the metadata will be imported from the returned JSON. For example, the genres list since tags are currently supported.

---

I think selectChapter(id) & nextPage() work fine and don't need to be changed, but let me know what you think.

I've based the variables around what the MangaDex & CatManga API normally return, so designing plugins for these should be easy. Other sites should be good too, since all these new variables are optional.

Let me know if there are anything that can be improved! :)

[hkalexling]

Sorry for the long delay, and thanks for taking on this!

Backward compatibility won't be an issue because we should let plugin developers specify the API version they are targeting. For example, we can add a version field in the info.json file. If it's not specified, we assume it's v1.

Everything else looks good as a first draft. Now I just need to take some time to actually implement this into the main app, and along the way I might be able to find ways to improve the draft. Again thanks a lot for the help! Feel free to throw in any new ideas.

[hkalexling]

I put together something here: https://github.com/hkalexling/mango-plugins/wiki/Development-Guideline-v2-(RFC). The new API would allow authentication (with the new settings field in info.json), manga searching (with searchManga(query)), chapter filtering, and auto-download of new chapters (with the optional newChapters() function).

Feel free to let me know if you have any suggestions!

[browningluke]

That looks really nice! The newChapters() will be really useful.

I do have a question regarding the manga/chapter ID. Currently the id can only contain alphanumerical characters or underscores, is this a limitation of Duktape, and if not, would it be possible to allow more special characters?

For sites that have a backend API, they usually have a mangaID that fits within the current limitations, but sites that have to be scraped, the manga ID ends up having to contain either key parts of the URL or the entire URL itself.

If it's the former, extra encoding/decoding has to occur to extract these parts (e.g. storing the chapter ID of a chapter like 11.5 as: MANGAID_ch11_5). If it's the latter, the only way to encode it is with base64 which ends up ruining the column sizing of the table in the UI, which could be fixed by not displaying the chapter/manga ID in the table.

Other than that, I don't have any suggestions. Thank you for the time you spend on mango!

[hkalexling]

Ah yes good point! Currently we are doing some hacky string manipulation to retrieve the plugin ID and chapter ID, so we don't want them to contain hyphens.

https://github.com/hkalexling/Mango/blob/8829d2e237889d0ec232a92a485b3ef4086ecaa0/src/queue.cr#L70-L74

I think we can get rid of this hacky code and directly store the two IDs explicitly in the DB. In this way we don't have to restrict the chapters in the chapter IDs. Thanks for the suggestion!