GraphQL on top of Spotify API = 🎆

Charly Poly
Apr 19, 2017 · 3 min read

Playing with the Spotify Web API has never been so simple.

Hi. 👋

As a music lover, I’m really interested in understanding the magic behind music, by learning music theory, playing guitar and singing.

However, I wanted to combine my two passions by building web-projects around music.
I quickly discovered the Spotify Web API, with all the data I needed — even more with audio features/analysis.

This post is the first about my journey on building tools and web-products on top of Spotify, I hope you’ll enjoy it!

Why using GraphQL for Spotify Web API ?

REST is cool, however it’s a total nightmare to fetch data like :

“Fetch all current user playlists with associated tracks and artists data”

Even with async, Promise or when.js, you ended up with a complex “data fetching” and data formatting code.
I started a prototype using the awesome spotify-web-api-node library :

Image for post
Image for post

This code excerpt does not handle pagination, exceptions, data formatting.
Not that satisfying. 😣

I quickly remembered this awesome project called GraphQL created by Facebook and applied the do not reinvent the wheel rule.
I decided to write a library called spotify-graphql

Okay, what is this awesome “GraphQL”?

I will quote the tagline of

What it means is that GraphQL is basically a query language for APIs — in fact it can be what you want.

GraphQL is a library that offer a query language and allows you to define how it should fetch the data using resolvers.

For a more “in depth introduction”, I strongly recommend reading
So what’s this GraphQL thing I keep hearing about?

Querying Spotify with spotify-graphql

Remember the following statement ?

“Fetch all current user playlists with associated tracks and artists data”

Here’s how you do it with spotify-graphql :

Image for post
Image for post

10 lines and you end up with a well formatted data object. 🎉

Features added on-top of GraphQL ❤️

the library with paginate automatically for you by inspecting API responses.
However you can set explicit rules by using query params.

me {
playlists(limit: 10)

API rate limit avoider
Fetching a lot of data with GraphQL can aim to do a lot of simultaneous requests.
To avoid that, SpotifyGraphQL is shipped with a throttle system and non-concurrency system.
In short, by default, SpotifyGraphQL will perform request in sequence of 2ms spaced calls.

embedded LRU cache
Throttling on big request can results of very long queries.
To avoid performing many times the same requests, SpotifyGraphQL uses a LRU cache, based on resources/params couple.

aliases with “search-on-the-fly”
One “hipster feature” of SpotifyGraphQL is “search on the fly”.

artist(name: "Kendrick Lamar") {
top_tracks {
track {

However, beware of this feature, there is no way to ensure that the search by name will return the desired Artist/Track.

Spotify GraphQL Console

In order to share the fun, I built a web Spotify Graph Console — featured in the Spotify Developer Showcase 🎉.

Image for post
Image for post

It allows you to play with Spotify API, without having to code.

Have fun and please report issue if you find some!

What’s next


  • 100% read-only endpoints coverage
  • rewrite of spotify-web-api-node (with caching and 100% API coverage)
  • improved stability, more tests
  • Release target date : June 2017

I hope you had fun reading this article and that you will have fun playing with SpotifyGraphQL.

I can’t wait to share with you my progress on upcoming projects, to find out more, please read Building tools and web-products on top of Spotify APIs”.

PS: If you liked this article, please “leave a star” on spotify-graphql 🤗

The French House

French mates that love web.

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer — welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store