topic Re: New Reference docs are unclear in Spotify for Developers

New Reference docs are unclear

clairefro — Fri, 22 Oct 2021 21:24:32 GMT

Not a fan of the newly styled Reference docs - the old docs were great

The new version changed the categories in a way that doesn't make sense. For example, the Browse category was removed and now "Get Recommendations" is under "Artists", even thought the endpoint return tracks and takes seed artists, tracks, and genres.

Important documentation is now missing on using filters in /search ?q= queries (ex: "?q=track:{track}+ artist:{artist}"). Filters can be partially inferred from /search ?type param description, but mostly we now have to guess the categories.

The old docs were easier to read with the examples in a black panel on the right, using the full API URL. The base URL can now be found on the Reference page overview, but it's not as simple to use these docs to teach about APIs as the old docs.

Also confusing that the old docs style and categories still live on the Console section: https://developer.spotify.com/console/browse/

The old Reference docs were great, please bring them back 🙂

Re: New Reference docs are unclear

spotifyjosh — Fri, 29 Oct 2021 22:54:59 GMT

Thanks for the detailed feedback, @clairefro, and for bearing with us. The recommendations endpoint can be found in the 'Tracks' category now and we've made some updates to the search API reference page. I will be sure to share your other suggestions with the team for consideration, too.

Re: New Reference docs are unclear

clairefro — Tue, 02 Nov 2021 20:06:19 GMT

Much appreciated @spotifyjosh! This makes more sense. I'm giving a demo in an hour and will be showing off you API 🙂