The API for interacting with the Spotify Playlist Guard application.
This project is a web server that provides an API for of the Spotify Playlist Guard application. This API provides services for registering users and their collaborative playlists to the Playlist Guard routine. For a detailed overview of all the routes and responses of this API, access the documentation:
This is the codebase of the API for registering Spotify users and their collaborative playlists to be guarded from unthaurized editing. Please check the other app related to this project:
- Spotify Playlist Guard: An application tha performs a guard routine periodically removing, from selected playlists, tracks added by unauthorized users;
- Spotify Playlist Guard Website: A web app for configuring spotify collaborative playlists to be guarded by the guard bot;
The User entity stores all the data related to a Spotify user. It is based on the user's data response from the Spotify Web API 'Get User's'Profile' endpoint and it shares the same Spotify user ID with the one from the Spotify system. This entity also stores the collaborative playlists owned by the user and chosen to be registered to this API's service.
The Playlist entity stores the data related to a Spotify playlist and it is based on the playlist's data response from the Spotify Web API 'Get Playlist' endpoint it shares the same Playlist Spotify ID with the one from the Spotify system.. It also contains a set of Spotify users ID's defined by the owner user of the playlist. This users ID's represent the ones allowed to add and delete tracks from the guarded playlist.
The Admin User stores the data of a different type of user, which has administrator privileges for managing operations of this API application such as creating and aupdating External Apps. Also, this entity does not represent a common Spotify user and does not store any Spotify data nor registered playlists to be guarded.
The External App entity represents the other projects related to this API that has access to some routes and access them with the following credentials: a CLIENT ID and a CLIENT API KEY.
All entities have routes for writing, reading, updating and deleting data related to it. The User entity, specifically, does not have a route for creation because this operation is performed during the first login of the user using the Spotify OAuth2 authentication process. Also, every time users log in, all their data (except the registered playlists) are automatically synced with the Spotify service and updated.
This projects uses three strategies for authentication of its users and clients: OAuth2, JWT and API Key.
The OAuth2 strategy is used mainly for the authentication of active Spotify users every time they login to this application.
The JWT strategy is used on two scenarios:
- Manage authenticated state of logged users. Right after a user logs in with the OAuth2 strategy, a JWT is generated so the application can manage the user's session.
- Authenticate admin users with their email and password and manage their session state.
The API key strategy is used for authenticating external apps on certain routes. With this strategy, the external app provides a CLIENT ID and a CLIENT KEY.
This project uses the NestJS framework, and, therefore, uses its modularized architecture with each functionality contained in a dedicated folder with a module wrapper for all its providers and resources. For more information, please check out NestJS official documentation.
- TypeScript as language;
- NestJS as web framework;
- Passport as an authentication lib along with:
- passport-spotify for OAuth2 authentication with the Spotify service;
- passport-jwt as JWT strategy;
- passport-local for authentication with username and password;
- Spotify Web API with spotify-web-api-node as client wrapper;
- PostgreSQL as database, using:
- Prisma as ORM;
- ElephantSQL as cloud service for PostgreSQL;
- GitHub Actions as CI/CD tool;
- Render as cloud server host;
Also , the tools used in the development environment:
Requirements:
- Docker for deskop installed in your machine;
- Docker Compose (The Windows and Mac versions of Docker Desktop include Docker Compose in their installation, so you only need to install it separately if you are using the Linux version);
- NodeJS and npm installed in your machine;
- A terminal of your choice.
Steps:
- Clone this repo on your local directory;
- In the terminal, enter the created directory and run the following command to install all the dependencies:
npm install -y
- Create a .env file based on the .env.example in this project and insert the values of the vars based on your development environment.
Note: When running both the app and the database as a containers, the POSTGRES_HOST env var must be set to 'postgres';
- Initialize the Docker app in your machine and run the following command at the root of your directory to build the image of the app, start the containers and intialize the them:
npm run build-start-containers
Note: When using a linux distribution, if there is a .docker folder with volumens inside, it may be necessary to run 'sudo rm -r .docker' to remove the old volumes before running the build script since that folder is created with root permission;
The application will then be available at 'http://localhost:3000'
- Once the containers and volumes are created in your machine, simply use the commands to start and stop them:
docker-compose start
docker-compose stop
- Create a .env file based on the .env.example in this project and insert the values of the vars based on your development environment.
Note: When running the the app locally, the POSTGRES_HOST env var must be set to 'localhost';
-
Remove the 'main' service of the docker-compose.yml file;
-
Initialize the Docker app in your machine and run the following command at the root of your directory to intialize the containers of the external services:
docker-compose up -d
- Run the following command to run the app in development mode:
npm run start:dev
- For a production-like running app, run the following commands:
npm run build
npm run start:prod
The application will then be available at 'http://localhost:3000'
This project uses Convention Commit with AngularJS's commit message convention specifications for standard commit messages.
Git hooks compliant with the commit guidelines and linting of the projet are defined in the ./husky folder. The hooks are disabled by default and can be enabled or disabled using the commands:
npm run enable-hooks
npm run disable-hooks
Spotify Playlist Guard API is published under MIT license