Follows/CustomList API Changelog - BREAKING CHANGES

[BraveDude8]

The following is copied from our #api-changelog channel on Discord.

Hello fellow devs !
We never liked how follow, reading statuses and custom list worked. Our ultimate goal was to make something similar to YouTube playlists and it's now coming to MangaDex !
We totally revamped CustomList and removed Follows and ReadingStatus so everything is a CustomList. You will have "default" CustomList that is where you Manga will be added by default, and also "pinned" CustomList that will be available in the Library page.
And we added the Subscription concept that allows you to subscribed to one or multiple CustomList. It will populate your feed with chapters matching what you subscribed to !

Also, for consistency, we replaced the "follows" keyword by "bookmark" and removed any endpoint that is related to Manga follows.

Here is the (really long) full changelog for the coming changes:

• Migrated all MangaReadingStatus to CustomList, which means 6 CustomList were created: "Reading", "On Hold", "Plan to Read", "Dropped", "Re-reading" and "Completed". Additionally, we created a "Follows" CustomList containing all Manga you were following and that is the default one (to reproduce current Updates feed). If you had no Manga with a reading status or follows, we will create you a default CustomList called "Reading"
• All migrated CustomList are pinned and should appear in Library page on MD frontend
• While creating all theses CustomList, we added a Subscribtion on the "Follows" CustomList. Subscription is what will appear in your update feed.
• All new User will have a "Reading" CustomList with a Subscription (set as default & pinned)
• You can't remove your last CustomList, because you always need at least one.
• You can't remove your default CustomList
• Added GET /list/default endpoint to get your logged User default CustomList
• Added POST /list/{id}/default to flag a given CustomList as default
• Added POST /list/{id}/pin and POST /list/{id}/unpin endpoints to flag or unflag given CustomList as pinned
• Added a filter on GET /user/list and GET /user/{id}/list to get pinned CustomList
• Added GET /user/list/manga/{id} endpoint to get all CustomList where given Manga ID is in for the logged User
• Added GET /user/subscription/{id} endpoint to know if given CustomList ID is subscribed by the logged User
• Added POST /list/{id}/batch-manga and DELETE /list/{id}/batch-manga endpoints to batch add/remove Manga to a given CustomList
• Create new Subscription resource:
  • Added GET /subscription List all subscriptions for the logged User
  • Added POST /list/{id}/subscribe and DELETE /list/{id}/subscribe add and remove a CustomList from your subscriptions
  • Added GET /subscription/feed Get the latest chapters for your subscribed CustomList manga
• Improve CustomList resource
  • Added GET /list/{id}/manga to list Manga in a given CustomList
  • Added GET /manga/{id}/list endpoint to get all CustomList for the logged User where a given Manga is in
• Manga follows endpoint were removed since their old behavior was replaced by subscription and old follows are migrated into the "Follows" CustomList
• Removed all reading status endpoints since it was replaced by CustomList and Subscription resources
• Deprecate follows key in Statistics endpoint, it was replaced by bookmarks, please change as soon as possible.
• Renamed followedCount sort to bookmarkedCount in ScanlationGroup lists, old sort will still work during the deprecation period but will get removed, please change as soon as possible.
• All follows endpoint were moved to a new Bookmark resource since the name better fits its new usage (since we want a clean migration, old Follow endpoints are deprecated but still working, please use the new Bookmark endpoints as soon as possible)
• POST /group/{id}/follow -> POST /group/{id}/bookmark
• DELETE /group/{id}/follow -> DELETE /group/{id}/bookmark
• GET /user/follows/group -> GET /user/bookmarks/group
• GET /user/follows/group/{id} -> GET /user/bookmarks/group/{id}
• POST /list/{id}/follow -> POST /list/{id}/bookmark
• DELETE /list/{id}/follow -> DELETE /list/{id}/bookmark
• GET /user/follows/list -> GET /user/bookmarks/list
• GET /user/follows/list/{id} -> GET /user/bookmarks/list/{id}
• POST /user/{id}/follow -> POST /user/{id}/bookmark
• DELETE /user/{id}/follow -> DELETE /user/{id}/bookmark
• GET /user/follows/user -> GET /user/bookmarks/user
• GET /user/follows/user/{id} -> GET /user/bookmarks/user/{id}
• Since we changed the purpose of Follow endpoints (and renamed them) and added the Subscription resource, we removed GET /user/follows/manga/feed and GET /user/follows/manga/{id} endpoint, please use GET /subscription/feed which serves the same purpose
• Added subscribedCount sort on Manga list
• Added endpoints to set a CustomList as default or pinned:
  • POST /list/{id}/default set given CustomList as default (and remove old default one)
  • POST /list/{id}/pin set given CustomList as pinned
  • POST /list/{id}/unpin remove pinned flag from given CustomList
• Added two temporary endpoints:
  • GET /list/migrated (logged user only) -> Tells if the logged User has been migrated or not (ok if migrated, ko if not)
  • POST /list/force-migration (logged user only) -> Will force the CustomList v2 migration for the logged User

All the changes are available in dev environment of MangaDex API, we will warn you guys before any release date but expect this to come any time soon. Here is a cool image that TL;DRs the update.

And in case this worries some at first glance: This model supports all the current features of your library and lists. None of those will be lost as a result.

The only practical difference is that you will now get to customize your reading statuses (once it hits prod anyway, since right now it's only on dev).
Renaming them, adding new ones, removing default ones, etc.

This will allow us to support two very orthogonal use-cases that have been asked for a long time:
1 single status for those of you that just want to "follow" 2000 titles with absolutely zero organization, revelling in the absolute chaos of that
100 different statuses because you really really really insist on having the most precise reading statuses imaginable (however questionably useful they might be)

Additionally, and while timelines for this being publicly available are blurry, the end-goal of this scheme is to allow you to do things like subscribing to someone else's list (some sort of curator kind of relationship in that regard), import it quickly into your own, and more.

 

[Tristan__]

first

GET /list/migrated (logged user only) -> Tells if the logged User has been migrated or not (ok if migrated, ko if not)

why ok and ko tho instead of true and false?

 

[rdn]

first

why ok and ko tho instead of true and false?

because ko and ok is cuter

 

[panda__________]

first

why ok and ko tho instead of true and false?

Also, we already have similar stuff in API and they all use ko and ko, it's to keep consistency with our API.

 

[TestAddress]

first

why ok and ko tho instead of true and false?

TF??