Skip to content

Latest commit

 

History

History
433 lines (384 loc) · 8.38 KB

api.md

File metadata and controls

433 lines (384 loc) · 8.38 KB

Below are examples of requests and responses for each of the APIs defined in your Django project. I'll assume your API is hosted at http://localhost:8000/.

1. Song List and Create API

Endpoint: GET /song/

Example Request:
GET http://localhost:8000/song/
Example Response:
[
    {
        "id": 1,
        "name": "Imagine",
        "author": "John Lennon",
        "album": "example album",
        "duration": 183,
        "lyrics": "Imagine all the people...",
        "topics": "Peace, Unity, Hope",
        "mp3_url": "http://example.com/song1",
        "cover_url": "http://example.com/images/imagine_cover.jpg"
    },
    {
        "id": 2,
        "name": "Bohemian Rhapsody",
        "author": "Queen",
        "album": "example album",
        "duration": 354,
        "lyrics": "Is this the real life? Is this just fantasy?",
        "topics": "Drama, Emotion, Storytelling",
        "mp3_url": "http://example.com/song2",
        "cover_url": "http://example.com/images/bohemian_rhapsody_cover.jpg"
    }
]

Endpoint: POST /song/

Example Request:
{
    "name": "Hey Jude",
    "author": "The Beatles",
    "album": "example album",
    "duration": 430,
    "lyrics": "Hey Jude, don't make it bad...",
    "topics": "Encouragement, Love, Friendship",
    "mp3_url": "http://example.com/heyjude",
    "cover_url": "http://example.com/images/hey_jude_cover.jpg"
}
Example Response:
{
    "id": 3,
    "name": "Hey Jude",
    "author": "The Beatles",
    "album": "example album",
    "duration": 430,
    "lyrics": "Hey Jude, don't make it bad...",
    "topics": "Encouragement, Love, Friendship",
    "mp3_url": "http://example.com/heyjude",
    "cover_url": "http://example.com/images/hey_jude_cover.jpg"
}

2. Song Retrieve/Update/Delete API

Endpoint: GET /song/<int:pk>/

Example Request:
GET http://localhost:8000/song/1/
Example Response:
{
    "id": 1,
    "name": "Imagine",
    "author": "John Lennon",
    "album": "example album",
    "duration": 183,
    "lyrics": "Imagine all the people...",
    "topics": "Peace, Humanity, Hope",
    "mp3_url": "http://example.com/song1",
    "cover_url": "http://example.com/song1-cover.jpg"
}

Endpoint: PUT /song/<int:pk>/

Example Request:
{
    "name": "Imagine",
    "author": "John Lennon",
    "album": "example album",
    "duration": 200,
    "lyrics": "Imagine all the people living life in peace...",
    "topics": "Peace, Humanity, Hope",
    "mp3_url": "http://example.com/song1-updated",
    "cover_url": "http://example.com/song1-cover-updated.jpg"
}
Example Response:
{
    "id": 1,
    "name": "Imagine",
    "author": "John Lennon",
    "album": "example album",
    "duration": 200,
    "lyrics": "Imagine all the people living life in peace...",
    "topics": "Peace, Humanity, Hope",
    "mp3_url": "http://example.com/song1-updated",
    "cover_url": "http://example.com/song1-cover-updated.jpg"
}

Endpoint: DELETE /song/<int:pk>/

Example Request:
DELETE http://localhost:8000/song/1/
Example Response:
{
    "detail": "Song deleted successfully."
}

3. Song Search API

Endpoint: GET /song/search/

search=keyword limit=X ai=True

Example Request:
GET http://localhost:8000/song/search/?search=Imagine&limit=20
Example Response:
[
    {
        "id": 1,
        "name": "Imagine",
        "author": "John Lennon",
        "album": "example album",
        "duration": 183,
        "lyrics": "Imagine all the people...",
        "topics": "Peace, Humanity, Hope",
        "mp3_url": "http://example.com/song1",
        "cover_url": "http://example.com/song1-cover.jpg"
    }
]

4. Favlist List and Create API

Endpoint: GET /favlist/

Example Request:
GET http://localhost:8000/favlist/
Example Response:
[
    {
        "id": 1,
        "name": "Chill Vibes",
        "songs": [1, 2]
    }
]

Endpoint: POST /favlist/

Example Request:
{
    "name": "Workout Jams",
    "songs": [2, 3]
}
Example Response:
{
    "id": 2,
    "name": "Workout Jams",
    "songs": [2, 3]
}

5. Favlist Retrieve/Update/Delete API

Endpoint: GET /favlist/<int:pk>/

Example Request:
GET http://localhost:8000/favlist/1/
Example Response:
{
    "id": 1,
    "name": "Chill Vibes",
    "songs": [1, 2],
    "songs_detail": [
        {
            "id": 1,
            "name": "Imagine",
            "author": "John Lennon",
            "album": "example album",
            "duration": 183,
            "lyrics": "Imagine all the people...",
            "topics": "Peace, Unity, Hope",
            "mp3_url": "http://example.com/song1",
            "cover_url": "http://example.com/images/imagine_cover.jpg"
        },
        {
            "id": 2,
            "name": "Bohemian Rhapsody",
            "author": "Queen",
            "album": "example album",
            "duration": 354,
            "lyrics": "Is this the real life? Is this just fantasy?",
            "topics": "Drama, Emotion, Storytelling",
            "mp3_url": "http://example.com/song2",
            "cover_url": "http://example.com/images/bohemian_rhapsody_cover.jpg"
        }
    ]
}

Endpoint: PUT /favlist/<int:pk>/

Example Request:
{
    "name": "Evening Relaxation",
    "songs": [1]
}
Example Response:
{
    "id": 1,
    "name": "Evening Relaxation",
    "songs": [1]
}

partially modify:

Endpoint: PATCH /favlist/<int:pk>/

Example Request:
{
    "name": "PATCH",
}
Example Response:
{
    "id": 1,
    "name": "PATCH",
    "songs": [1]
}
Example Request:
{
    "songs": [1, 2],
}
Example Response:
{
    "id": 1,
    "name": "PATCH",
    "songs": [1, 2]
}

Endpoint: DELETE /favlist/<int:pk>/

Example Request:
DELETE http://localhost:8000/favlist/1/
Example Response:
{
    "detail": "Favlist deleted successfully."
}

6. User Favorites List and Create API

Endpoint: GET /userfav/

Example Request:
GET http://localhost:8000/userfav/
Authorization: Bearer <JWT_TOKEN>
Example Response:
[
    {
        "user": 1,
        "favlists": [1, 2]
    }
]

Endpoint: POST /userfav/ (Deprecated)

Example Request:
{
    "favlists": [1]
}
Example Response:
{
    "user": 1,
    "favlists": [1]
}

7. User Favorites Retrieve/Update/Delete API

partially modify:

Endpoint: PATCH /userfav/

Example Request:
{
    "favlists": [2]
}
Example Response:
{
    "user": 1,
    "favlists": [2]
}

Endpoint: DELETE /userfav/

Example Request:
DELETE http://localhost:8000/userfav/1/
Authorization: Bearer <JWT_TOKEN>
Example Response:
{
    "detail": "User favorites deleted successfully."
}

8. AI Generate Songs API

Endpoint: GET /generate-songs/<int:pk>/

Example Request:
GET http://localhost:8000/generate-songs/1/
Example Response:
[
    {
        "id": 1,
        "name": "The Rhyme Chronicles",
        "author": "SunoAI",
        "album": "SunoAI Generation",
        "duration": 189,
        "lyrics": "[Verse 1]\nGot the city lights flickerin..",
        "topics": "",
        "mp3_url": "https://cdn1.suno.ai/ee0717ad-aded-4008-a30c-4f43bbcb3fc3.mp3",
        "cover_url": "https://cdn2.suno.ai/image_ee0717ad-aded-4008-a30c-4f43bbcb3fc3.jpeg"
    },
    {
        "id": 2,
        "name": "The Rhyme Chronicles",
        "author": "SunoAI",
        "album": "SunoAI Generation",
        "duration": 97,
        "lyrics": "[Verse 1]\nGot the city lights flickerin..",
        "topics": "",
        "mp3_url": "https://cdn1.suno.ai/7d47a123-b4e0-436d-8b01-6e9acbc5f1bf.mp3",
        "cover_url": "https://cdn2.suno.ai/image_7d47a123-b4e0-436d-8b01-6e9acbc5f1bf.jpeg"
    }
]

test

curl -X POST http://localhost:8000/userfav/ ^
-H "Content-Type: application/json" ^
-d "{\"favlists\": [2, 3]}" ^
--user "heaplax"

curl -X PUT http://localhost:8000/userfav/ ^
-H "Content-Type: application/json" ^
-d "{\"favlists\": [2]}" ^
--user "heaplax"