API v4 - Reference

[paglias]

Changes with performance benefits

Users Inbox Messages

DONE ~~There’s no limit to the amount of messages stored in each user’s inbox and for users with a lot of messages the inbox takes several hundred KBs of space for each user document and make up 90%+ of the entire user document size.~~

This is causing some operations to be considerably slow as shown in this issue https://github.com/HabitRPG/habitica/issues/10422.

The idea is to move inbox messages to their own collection like we did for chat messages in groups.~~

Users and Tasks History Entries

Two new history entry are added per day for each user (one for todos and one for experience points), one per day is added when a daily or habit is scored.

While these entries get condensed over time, in particular for subscribed users we can reach 365 history entries (with two data points each) for each task and user, which end up taking most of the size of each task document.

This history entries are loaded every time a task or user is fetched from the database but they’re used extremely rarely in the code and right now no official client (web and mobile apps) uses them. So they have a big impact on performances with very little benefit in terms of features for end users. The idea is to move these history entries in separate documents and retrieve them only when necessary. (To decide: do we want one MongoDB document for each history entry - better but will require huge amounts of RAM to store the indexes - or one single doc to store the entire history for each task and user).

Group Chat Messages

A previous PR has already moved chat messages to their own collection but to keep backward compatibility with the API v3 specs they’re always returned when a group object is returned by the API even if the client doesn’t need the chat messages. The idea is to update or create new API routes to make sure the chat messages are only fetched when necessary.

New API features

Tasks Bulk Scoring (Also in cron route)

I have a request for v4 (this isn't even breaking, so it could also be v3 but if we are making changes it fits: allow to pass tasks that are supposed to be checked off to the runCron API. Ideally also with a way to check off checklist items. That way that whole process can be done in a single API call instead of a bunch of calls like the apps are doing right now

Yea, so bulk score plus do it in the Cron call. I'm for it

Other changes (mostly for consistency)

• user.inbox.optOut and other preferences: move to user.proferences
• Groups invitations in one single place: remove them from user.invitation and user.invitations and only use user.notifications?
• ReadNotification: shouldn't return the entire user.notifications object
• ReadNotifications: shouldn't return the entire user.notifications object, because the response middleware returns all the notifications anyway. Same for SeeNotifications
• user.invitations.party should be removed in favor of user.invitations.parties
• Move all notifications to user.notifications (including party, guilds, quests invitations)
• flags.newStuff deprecated in favor of proper notification?
• flags.{xxx}Received now have proper notifications, so we could stop storing the sender name there and just keep track of how many they have received?
• remove user.newMessages in favor of user.notifications
• remove user._tmp in favor of notifications

[Alys]

API v3's Leave a group route takes an optional body parameter keepChallenges, which can be either remain-in-challenges (the safest option for any client to implement) or leave-challenges (the default but usually undesirable). https://github.com/HabitRPG/habitica/blob/88188e56d988176cedac0816893290b1ca4f4ac5/website/server/controllers/api-v3/groups.js#L736-L748

I'd like API v4 to have remain-in-challenges as the default. It would fix this issue: https://github.com/HabitRPG/habitica-android/issues/906#issuecomment-352192468

[paglias]

The inbox now supports pagination for both messages and conversations (should be made mandatory before v4 is released). Also merge /inbox/messages and /inbox/paged-messages