APIv4 Wishlist

[jvyden]

This is an epic, and will grow over time as I think of changes that should be made for the next iteration of the API.

• Move all level statistics into a dedicated statistics object (ref. Implement various API extensions #517)
• Remove events array from Recent Activity endpoints (ref. Overhaul & rewrite serialization of Recent Activity #782)
• Include all personal relations of a user to a level (by @Toastbrot236)
• Rework admin endpoints to allow direct manipulation of database objects
• 2-way OAuth support for integrating with other applications (both apps integrating with Refresh, and Refresh integrating with apps)
• Remove multi-key lookups (e.g. only have {uuid} endpoints instead of {uuid} and {username}). Addresses developer strain mentioned in Implement admin endpoints for Reviews & Comments #845.
• Support warnings for all API responses
• Validation exceptions & clean handling for them

For compatibility with older clients, it's possible we could have a tiny go server or something that provides a translation layer from APIv4 to APIv3. Would probably be a bit messy to have in the Refresh solution.

[Toastbrot236]

Another idea: Maybe have the personal relations of a user to a level (own play count, has hearted, has queued etc) still be in a dedicated ApiGameLevelRelationsResponse object, but include that object in the level's response instead of only returning it with a separate endpoint? Would let clients show the user's relations for an entire list of levels at once (similarly to how the game does it) instead of just for one individual level.
This could then probably also be extended to showing personal relations towards users, playlists etc.

[Toastbrot236]

A few more ideas:

• Split profile updates (icon, description) from authentication updates (email address, PSN/RPCN auth etc) into separate endpoints, would allow us to block profile updates in some cases while still allowing auth updates
• Require reasons for most (or all) moderation actions
• Always send enum values as strings instead of numbers (e.g. Level or Plan instead of 6 or 31), clients would no longer have to copy the entire enum + unknown values would be displayed in a human-readable way instead of a seemingly random number; for requests we could probably expect both numeric and string values