Description
This is a collection of points based on the feedback received over time and my general thoughts. Better formatting of returned data can help improve developer experience.
Most of these would be destructive and non-backward compatible changes to the response schema so we'd have to target major parser and REST API versions.
Enumification of known values
Some properties are returned from MAL as-is currently but they are limited and known values. It would be a good idea to create constants for them at parser-level. This would make validation easier to handle on both parser and REST API.
Some properties that come to mind from Anime/Manga type resources are:
typesourcestatusrating
Note: These can be nullable.
Note2: These can have their own listing endpoints like Anime Genres in case users might not want to hard code these values and keep them dynamic client-side.
Duration to Seconds
Currently, duration is returned as a string, we should convert them to seconds so devs can format them easily.
Feedback received here: https://discord.com/channels/460491088004907029/462992340718583814/1102217962577997964
Proposed Schema:
"duration": {
"seconds": 5400,
"string": "1h 30m"
}Date Props to not estimate
Related issue: #486
Currently, if the date range receives something like "2024", it will assume the starting date is "1 January, 2024". It would be better to keep those unknown prop values as null.
Current Schema:
"aired": {
"from": "2024-01-01T00:00:00+00:00",
"to": null,
"prop": {
"from": {
"day": 1,
"month": 1,
"year": 2024
},
"to": {
"day": null,
"month": null,
"year": null
}
},
"string": "2024 to ?"
},Proposed Schema:
"aired": {
"from": "2024-01-01T00:00:00+00:00", // we "estimate" here
"to": null,
"prop": {
"from": {
"day": null, // returns null here
"month": null, // returns null here
"year": 2024
},
"to": {
"day": null,
"month": null,
"year": null
}
},
"string": "2024 to ?"
},Opening/Ending Themes
Currently, we're just returning array of strings. We're not doing any further parsing at the moment. But, there is some metadata in there that we can parse and return separately. Like the episode range those OP/EDs were played in.
Related issue: #534
Current Schema:
"openings": [
"1: \"We Are! (ウィーアー!)\" by Hiroshi Kitadani (きただにひろし) (eps 1-47,1000, 1089-)",
]Proposed Schema:
"openings": [
{
"titles": [
{
"type": "English",
"title": "We Are!",
},
{
"type": "Japanese",
"title": "ウィーアー!",
},
],
"author": {
"name": [
{
"type": "English",
"title": "Hiroshi Kitadani",
},
{
"type": "Japanese",
"title": "きただにひろし",
},
]
},
"episodes": ["1-47", "1000", "1089-"]
}
]The episodes data is provided in 3 different types:
- Ranges (e.g
1-47"Throughout episode 1 till 47") - Specific episode mentions (e.g
1000) - Ongoing range (e.g
1089-"Episode 1089 and onwards")
Furthermore, as a object we can link some additional data that is now returned as well. Like preview URLs for these OP/ED themes: #534 and (if any) attached music videos.
Returning null on placeholder URLs
Related issue: #488
cc: @pushrbx
What else is there? If anyone else has any suggestions, let's discuss it below.