Add missing api docs

[amCap1712]

Some of the api endpoints are absent from the api docs at listenbrainz.readthedocs.io. This is because we need to manually add new api blueprints to api.rst. This is only required when we use a new blueprint. Adding a new endpoint to a blueprint that is already documented (present in api.rst) does not need any extra changes.

We have also decided to use code-block directives for specifying json blocks in the documentation.

I think these details are generally useful in coding/reviewing apis and will add these to the checklist (to be created in the wiki).

[pep8speaks]

Hello @amCap1712! Thanks for updating this PR. We checked the lines you've touched for PEP 8 issues, and found:

• In the file listenbrainz/webserver/views/recommendations_cf_recording_api.py:

Line 64:131: E501 line too long (143 > 130 characters)

Comment last updated at 2021-04-21 14:48:39 UTC

[alastair]

Thanks for cleaning this up. I have a few questions about some of the new endpoints. It's not clear if we need to document these for users, or if they should stay internal.

[alastair]

Suggested change

	These API endpoints allow to submit and retrieve feedback for a user's recordings
	These API endpoints allow to submit and retrieve feedback recordings that a user has listened to

[alastair]

I don't understand what this API does. Is it things that are missing from MusicBrainz, or things that we've not successfully managed to link to MusicBrainz? What is the way that this is added, and why would a user want to access this data?

[amCap1712]

This is generated during matching the listens with the MBID mapping. The listens could not be matched that are used to create this data. The intent to add this data was for displaying it in some form on LB website so as to nudge users to add this data to MB.

Speaking in general regardless of whether the API is useful to users or not, I think putting it on the docs adds a little to the convenience of developers. I say this because docs are rendered in a more human readable form on readthedocs than the source.

In case, these endpoints adds noise for users, we should probably consider adding another different section to docs.

[alastair]

yeah, I'd consider adding this to a separate section not directly on the core submit/get documentation.

[alastair]

other than the comment about splitting the "Missing MusicBrainz Data" section to another page, this is fine