This is a microservice to fetch categories, genres, playlists, tracks, and songs saved by the user.

• Quick Start
  • Docker
  • GitHub
• Service Architecture
  • Endpoints
  • Utilities
    • Category Endpoint Utilities
    • Genre Endpoint Utilities
    • Playlist Endpoint Utilities
• Testing

This section explains how to get necessary files and deploy this app locally.

The quickest way to run this app locally on your machine is to pull the mborhi/spotify-quick-discover/retrieval-service from Dockerhub.

To do this, first make sure you have docker command tools installed your machine. Verify this by entering the following command in your terminal:

docker --version

If you get an error, you can install it on the official Docker page.

Pull the image by entering the following command:

docker pull mborhi/spotify-quick-discover/retrieval-service 

You now have the Docker image installed. If you have the Docker desktop app installed you can simply head over to the Images section and click run beside the image you just pulled. Otherwise, you can run the image using the run command:

docker run --rm -dp 3000:3000 mborhi/spotify-quick-discover/retrieval-service

Verify that the image is successfully running by visiting http://localhost:3000 in your preferred browser.

To stop the container, use the command:

docker stop mborhi/spotify-quick-discover/retrieval-service

Alternatively, you can clone this repository from GitHub and use the following commands to run the application on your local machine:

First install the necessary dependencies by running: npm install. Then, make sure to configure a .env file in the root of the directory, if you want to run the server on port different than 3000.

You are now ready to transpile and build the TypeScript files:

npm run tsc

Launch the server by using:

npm run start:prod

Verify that the server is live by visiting http://localhost:3000 in your preferred browser.

Simply press control-C in the terminal window running the server to stop the application.

This section outlines the architecture of this microservice, as well as its capabilities.

This microservice exposes six endpoints. Two for retrieving tracks and information of genres, two for retrieving tracks and infromation of categories, and two for managing the saved tracks in the the user's playlist.

• /categories/
  • GET request
  • retrieves available categories
• /categories/:category_id
  • GET request
  • retrieves tracks from the specfied category's playlists
• /genres/
  • GET request
  • retrieves available genres
• /genres/:genre_id
  • GET request
  • retrieves tracks from the specified genre
• /playlist/
  • GET request
  • retrieves the tracks saved in the user's "Quick Discover Finds" playlist
  • creates new playlist if user doesn't have one yet
• /playlist/tracks
  • POST request
    • adds the specified track to the user's playlist
    • creates new playlist if user doesn't have one yet
  • DEL request
    • removes the specified track from the user's playlist

You can find more documentation for these endpoints on the Postman Spotify Quick Discover Microservices workspace page.

To fulfill the services of each endpoint, a couple utilties functions are used.

To manage retrieving categories, a function fetches the relavent data from the Spotify Web API, and formats the data. This is then loaded into a Mongo database. If there are already categories stored within the database, instead of making another query to the Spotify API, the categories are loaded directly from the database. The database is updated every hour. Please see fetch-categories.ts for implementation documenation.

To retrieve tracks from a specific category id, a function fetches that category's playlists. Another function then processes this data to aggregate all tracks from the all the playlists. Since playlists are updated frequently, this data is never stored. Please see fetch-category-id.ts for implementation documentation.

To manage retrieving genres, a function fetches the relavent data from the Spotify Web API, and formats the data. This is then loaded into a Mongo database. If there are already genres stored within the database, instead of making another query to the Spotify API, the genres are loaded directly from the database. The database is updated every hour. Please see fetch-genres.ts for implementation documenation.

To retrieve tracks from a specific genre, a function uses the Spotify Web API's search endpoint to query for tracks matching that genre. This track data is then formatted. Please see fetch-genre-id.ts for implementation documenation.

Retrieving the user's playlist is done by first fetching all of the user's playlists and filtering for 'Quick Discover Finds' through the Spotify Web API. If this doesn't exist it will be created for the user. Once the playlist is obtained, the track information is processed the same way as for a category playlist.

A single function is used to handle both user playlist track addtions and deletions.

Endpoint testing is done on Postman through workflows: Spotify Quick Discover Microservices.

Utility testing is completed using the Jest testing framework.