Music API

Discover artists, albums, and songs with our API!

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation with Pip
   • Installation with Docker
   • Configuration Variables
3. Usage
• Endpoints
4. Usage Example
5. Add Dummy data
6. License
7. Contact

About the project

This API allows you to search for information about artists, albums, and songs. You can retrieve details such as the name, duration, description, and more for these entities. Additionally, this API provides a user authentication system using JWT for authorization and utilizes Redis cache to enhance performance and improve response times.

(back to top)

Built With

This is a web application built using Flask, Python, and SQLAlchemy. By default, the application is configured to use SQLite as the database backend. However, if you prefer to use a different database, you can easily switch to PostgreSQL by updating the configuration settings in the config.py file. Additionally, this application utilizes Redis for caching purposes, which helps improve performance and reduce the load on the database..

• 
• 
• 

(back to top)

Getting Started

Prerequisites

Before you start, you'll need to make sure you have the following installed:

• Python (3.11 or higher)
• Pip
• PostgreSQL (10 or higher)
• Redis
• Docker and Docker Compose (optional)

(back to top)

Installation with Pip

1. Clone the repository and change to the clones directory:

   git clone https://github.com/SSleimann/music-flask-api.git
   cd music-flask-api

2. Create a virtual enviroment for the project

   python -m venv venv

3. Activate the virtual enviroment:

   source venv/bin/activate

4. Install the project and its dependencies using pip:

   pip install .

5. Assign the environment variables:

   export FLASK_APP=musicapi.app

6. Run the application:

   flask run

(back to top)

Installation with Docker

1. Clone the repository and change to the clones directory:

   git clone https://github.com/SSleimann/music-flask-api.git
   cd music-flask-api

2. Run the following command to build and run the containers:

   docker compose up -d

3. You can stop the containers at any time with the following command:

   docker compose down

Configuration Variables

The following variables can be configured. These configuration variables are located in the .envs/.local dir and the docker-compose.yml file.

Variable	Description
SECRET_KEY	The secret key of the application.
JWT_SECRET_KEY	The secret key used to sign JWT tokens.
LOG_LEVEL	Logging level of the application.
DATABASE_URL	The URL of the PostgreSQL database used by the application.
POSTGRES_USER	The username used to authenticate with the PostgreSQL database.
POSTGRES_PASSWORD	The password used to authenticate with the PostgreSQL database.
POSTGRES_DB	The name of the PostgreSQL database used by the application.

(back to top)

Usage

To use this API, make an HTTP request to one of the endpoints using the appropriate HTTP method.

Endpoints

Method	Endpoint	Description	Request body	Request Header
POST	user/register	Register a new user.	username, email, password, password_confirmation	Content-Type: application/json
POST	user/login	Logs a user.	email, password	Content-Type: application/json
GET	user/profile	Retrieves the user information.	N/A	Authorization: Bearer <jwt_access_token>
GET	music/artist, music/artist/<id>	Retrieves artist information.	N/A	Authorization: Bearer <jwt_access_token>
POST, PUT, PATCH	music/artist, music/artist/<id>	Create/update a artist. (Need to be admin)	name, description, year_of_birth	Authorization: Bearer <jwt_access_token>
GET	music/album, music/album/<id>	Retrieves album information.	N/A	Authorization: Bearer <jwt_access_token>
POST, PUT, PATCH	music/album, music/album/<id>	Create/update a album. (Need to be admin)	name, artist_id, description, release_date	Authorization: Bearer <jwt_access_token>
GET	music/songs, music/song/<id>	Retrieves song information.	N/A	Authorization: Bearer <jwt_access_token>
POST, PUT	music/song, music/song/<id>	Create/update a song. (Need to be admin)	name, artist_id, album_id, duration, release_date	Authorization: Bearer <jwt_access_token>
DELETE	music/artist/<id>, music/album/<id>, music/song/<id>	Delete a artist/song/album. (Need to be admin)	N/A	Authorization: Bearer <jwt_access_token>

Pagination

Endpoint	Description
music/artist?page=<int>	Return 10 artists
music/album?page=<int>	Return 10 albums
music/song?page=<int>	Return 10 songs

Search

Endpoint	Description
music/artist?search=<string>	Search Artist records for search term in name field of Artist and related Song or Album
music/album?search=<string>	Search Album records for search term in name field of Album and related Artist or Song
music/song?search=<string>	Search Song records for search term in name field of Song, related Album or Artist tables.

(back to top)

Usage Example

Create a user admin

You need to open a Flask interactive console. To open the interactive console, open the terminal and run the following command:

flask shell

Then execute this:

from musicapi.models import User
from musicapi.app import db

user = User(username='adminuser', email='[email protected]')
user.set_password('password')
user.set_admin()

db.session.add(user)
db.session.commit()

Login a user

Request

POST {{API}}/user/login
content-type: application/json

{
    "email": "[email protected]",
    "password": "12345678"
}

Response

{
    "token": "<jwt_access_token>"
}

Creating a Artist

Request

POST {{API}}/music/artist
content-type: application/json
Authorization: Bearer <jwt_access_token>

{
    "name": "artist",
    "description": "hello",
    "year_of_birth": "1999-01-24"
}

Response

{
  "message": "Artist have been created successfully!",
  "artist": {
    "name": "artist",
    "description": "hello",
    "year_of_birth": "1999-01-24",
    "num_albums": 0,
    "num_songs": 0,
    "total_duration": 0
  }
}

Find Artist by Name and Paginate

Request

GET {{API}}/music/artist?search=weeknd&page=1
content-type: application/json
Authorization: Bearer <jwt_access_token>

Response

[
  {
    "name": "the weeknd",
    "description": "hello",
    "year_of_birth": "1999-01-24",
    "num_albums": 5,
    "num_songs": 6,
    "total_duration": 12121212
  },
  {
    "name": "2 weeknd",
    "description": "hello2",
    "year_of_birth": "1939-01-24",
    "num_albums": 1,
    "num_songs": 10,
    "total_duration": 150
  }
  ... (only 10 results per page)
]

(back to top)

Add Dummy Data

You can add dummy data to the application using the Flask interactive console. To open the interactive console, open the terminal and run the following command:

flask shell

Then execute this:

from musicapi.dhelper import DummyHelper

d = DummyHelper()
d.add_dummy_data()

The dummy data is intended for testing purposes only and is generated by ChatGPT. Therefore, it is not realistic and should not be used for production purposes.

(back to top)

License

This project is licensed under the GNU General Public License (GPL) version 3. See the LICENSE file for more details.

(back to top)

Contact

If you have any questions, comments, or issues related to the project, feel free to contact me. Sleiman Orocua.

(back to top)