[AUD-1375] Prepare User and Track APIs for Type Generation

[rickyrombo]

Description

Preview API docs: http://34.66.46.158:4567/#audius-api-docs

Users

• Renames <string:user_id> to <string:id> in the route params for users so that it doesn't conflict with the user_id query param and cause problems with the swagger.json output
• Creates current_user_parser, pagination_parser, and pagination_with_current_user_parser which can be used between different responses so we don't have to keep redefining the same parameters, and added help text explaining what the parameters are
• Fixes documentation for user challenges
• Fixes documentation for associated wallets/get user by associated wallet
• Changes some operation IDs to be better names, moving the more verbose descriptions to the description field

Tracks

• Split apart repeated OperationIDs (trending, underground trending, recommendations - anything with two routes) to two differently documented routes (still functionally equivalent) to get rid of operation ID conflicts
• Added descriptions and IDs to every route
• Ensured all params were documented and all requests had an expect
• TODO: Figure out what's going on with /by_id and the "explore" endpoints. I have some hot takes here, mainly as the explore endpoints are dependent on the user:
  • We shouldn't have a /by_id endpoint, we should update the root /tracks endpoint to take IDs
    • Also: needs to be authed for unlisted tracks via middleware?
  • tracks/under_the_radar isn't actually "Under the Radar" (yet) it's just a feed. It should be /my/feed* or /users/{id}/followees/activity (and be authed?)
  • Once we have under the radar for real on DN, it should be /my/smart-playlists/under-the-radar*
  • tracks/best_new_releases should be /my/smart-playlists/new-releases* (and be authed?)
  • tracks/most_loved should be /my/smart-playlists/most-loved* (and be authed?)

*For all of these, could also go for /users/{id} instead of /my or even just dropping the my, but I do like the idea of making it authed (no need to allow users to see each other's unless shared?) and grouping the smart playlists together. Open to ideas, but I don't think they should be on the root /tracks route and I prefer hyphens for routes over snake casing

Notes/Qs/Callouts

• Many endpoints are missing an offset for pagination. Seems intentional for some, but others might not necessarily need to be so restrictive (eg. remixables)?
• Limits are defaulted differently on some endpoints. Can we standardize? If not, I can do a pass and override as necessary. Did a pass and ensured default limits stay the same.
• Added caching in some places, double check that's ok? Removed this
• Same with @record_metrics?
  • Seems like this should be fine. Only added in a few full API endpoints
• Do we really need responses defined everywhere?
  • I vote no, but no change for now
• Was there a reason for the separate parser per route? Can add back via copy()s but wasn't sure if it was necessary. Might still be good to have for future maintenance?
  • Nobody seems to have an opinion on this
• Should probably generate the API docs and host them some where for a copy proofread
• Are there any APIs we want to make sure are always unlisted (even from our autogen?)
• Do we want to autogen full or non-full or both?
  • Autogenning both
• Get Track (v1/full) still uses get_unlisted_track. When is Marcus gonna clean this up??? 👀
  • GET ON IT
• Normalized attribute order as best I could. Up for debate, but for now I made the order:
  1. @record_metrics
  2. @api.doc
  3. @api.expect
  4. @api.marshal_with
  5. @cache

Tests

❗ There should be no functional changes from this PR ❗ - Everything I touched should only impact documentation. If you think something I did will affect functionality, let me know so I can make sure it gets tested. I do want to avoid testing each API individually 😨

How will this change be monitored? Are there sufficient logs?

[jowlee]

Thanks for doing this!

Some notes:

• I don't think we want to drop the trending version everywhere - as it is used when migrating default trending versions for a consistent user experience
• One things that's not consistent everywhere is the responses in the ns.doc - in some places we have it and in other we don't (Note that it's not too useful even when we have it bc it's the same everywhere)
• Since user_id was converted to id in the url params, do we want to update track_id to id in its respective route param for consistency? I don't it doesn't conflict so I'm fine either way

[jowlee]

nice!

[jowlee]

I don't think we want to drop the ability to specify the version - it should help with migrations of default trending versions

[rickyrombo]

I added FullRecommendedTracksWithVersion to replace this route here which the same thing. It needs to be separate so that they can have different operation IDs (we can't have two routes with the same ID)

[rickyrombo]

@jowlee Thoughts on leaving this out of the typegen/documentation? (and/or any other endpoints that might be worth hiding?)

[rickyrombo]

I don't think we want to drop the trending version everywhere - as it is used when migrating default trending versions for a consistent user experience

(addressed inline - it shouldn't be missing, just moved)

One things that's not consistent everywhere is the responses in the ns.doc - in some places we have it and in other we don't (Note that it's not too useful even when we have it bc it's the same everywhere)

Yeah I noticed this too - should we just remove it? I don't think it's adding any value...

Since user_id was converted to id in the url params, do we want to update track_id to id in its respective route param for consistency? I don't it doesn't conflict so I'm fine either way

No strong feelings here, I left it to reduce footprint of this change but could easily go the other way. I would have preferred to keep them user_id and track_id but alas the former I cannot, so I can see the argument for consistency.

[piazzatron]

Re: Added caching in some places, double check that's ok? - do we know which endpoints we added caching for? Would like to double check this is safe

[rickyrombo]

Added comments where cache was added

Removed added caching