ekkimukk/jukebox
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
4fb7b1691cce3efd2ac97a068c17310d77484818
jukebox/www/api/API_EXAMPLES.md
T
ekkimukk 4fb7b1691c Big commit whatever
2026-06-04 12:44:22 +02:00

20 KiB
Raw Blame History

Laravel Jukebox API - Request/Response Examples

1. Authentication

Register New User

Request:

POST /api/register
Content-Type: application/json

{
  "name": "John Doe",
  "email": "john@example.com",
  "password": "password123",
  "password_confirmation": "password123"
}

Response (201 Created):

{
  "token": "1|abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
  "user": {
    "id": 1,
    "name": "John Doe",
    "email": "john@example.com",
    "role_id": 2,
    "created_at": "2026-05-07T10:05:00.000000Z",
    "updated_at": "2026-05-07T10:05:00.000000Z",
    "role": {
      "id": 2,
      "name": "user",
      "created_at": "2026-04-21T00:00:00.000000Z",
      "updated_at": "2026-04-21T00:00:00.000000Z"
    }
  }
}

Login

Request:

POST /api/login
Content-Type: application/json

{
  "email": "john@example.com",
  "password": "password123"
}

Response (200 OK):

{
  "token": "2|abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
  "user": {
    "id": 1,
    "name": "John Doe",
    "email": "john@example.com",
    "role_id": 2,
    "created_at": "2026-05-07T10:05:00.000000Z",
    "updated_at": "2026-05-07T10:05:00.000000Z",
    "role": {
      "id": 2,
      "name": "user",
      "created_at": "2026-04-21T00:00:00.000000Z",
      "updated_at": "2026-04-21T00:00:00.000000Z"
    }
  }
}

Get Current User

Request:

GET /api/me
Authorization: Bearer {token}

Response (200 OK):

{
  "id": 1,
  "name": "John Doe",
  "email": "john@example.com",
  "role_id": 2,
  "created_at": "2026-05-07T10:05:00.000000Z",
  "updated_at": "2026-05-07T10:05:00.000000Z",
  "role": {
    "id": 2,
    "name": "user",
    "created_at": "2026-04-21T00:00:00.000000Z",
    "updated_at": "2026-04-21T00:00:00.000000Z"
  }
}

Logout

Request:

POST /api/logout
Authorization: Bearer {token}

Response (200 OK):

{
  "message": "Logged out."
}

2. Browse (Read-Only) Endpoints

List All Labels

Request:

GET /api/labels
Authorization: Bearer {token}

Response (200 OK):

[
  {
    "id": 1,
    "name": "Universal Music",
    "created_at": "2026-04-21T00:00:00.000000Z",
    "updated_at": "2026-04-21T00:00:00.000000Z"
  },
  {
    "id": 2,
    "name": "Sony Music",
    "created_at": "2026-04-21T00:00:00.000000Z",
    "updated_at": "2026-04-21T00:00:00.000000Z"
  }
]

Get Single Label

Request:

GET /api/labels/1
Authorization: Bearer {token}

Response (200 OK):

{
  "id": 1,
  "name": "Universal Music",
  "created_at": "2026-04-21T00:00:00.000000Z",
  "updated_at": "2026-04-21T00:00:00.000000Z"
}

List All Genres

Request:

GET /api/genres
Authorization: Bearer {token}

Response (200 OK):

[
  {
    "id": 1,
    "name": "Rock",
    "created_at": "2026-04-21T00:00:00.000000Z",
    "updated_at": "2026-04-21T00:00:00.000000Z"
  },
  {
    "id": 2,
    "name": "Pop",
    "created_at": "2026-04-21T00:00:00.000000Z",
    "updated_at": "2026-04-21T00:00:00.000000Z"
  }
]

List All Artists

Request:

GET /api/artists
Authorization: Bearer {token}

Response (200 OK):

[
  {
    "id": 1,
    "name": "The Beatles",
    "cover_path": "/images/beatles.jpg",
    "release_date": "1960-01-01T00:00:00.000000Z",
    "label_id": 1,
    "duration": null,
    "created_at": "2026-04-21T00:00:00.000000Z",
    "updated_at": "2026-04-21T00:00:00.000000Z",
    "label": {
      "id": 1,
      "name": "Universal Music",
      "created_at": "2026-04-21T00:00:00.000000Z",
      "updated_at": "2026-04-21T00:00:00.000000Z"
    }
  }
]

Get Single Artist (with Relations)

Request:

GET /api/artists/1
Authorization: Bearer {token}

Response (200 OK):

{
  "id": 1,
  "name": "The Beatles",
  "cover_path": "/images/beatles.jpg",
  "release_date": "1960-01-01T00:00:00.000000Z",
  "label_id": 1,
  "duration": null,
  "created_at": "2026-04-21T00:00:00.000000Z",
  "updated_at": "2026-04-21T00:00:00.000000Z",
  "label": {
    "id": 1,
    "name": "Universal Music",
    "created_at": "2026-04-21T00:00:00.000000Z",
    "updated_at": "2026-04-21T00:00:00.000000Z"
  },
  "tracks": [
    {
      "id": 1,
      "title": "Hey Jude",
      "file_path": "/music/hey-jude.mp3",
      "duration_seconds": 427,
      "album_id": 1,
      "created_at": "2026-04-21T00:00:00.000000Z",
      "updated_at": "2026-04-21T00:00:00.000000Z",
      "album": {
        "id": 1,
        "title": "Hey Jude",
        "cover_path": "/images/hey-jude.jpg",
        "release_date": "1968-08-26T00:00:00.000000Z",
        "duration_seconds": 427,
        "type": "single",
        "label_id": 1,
        "created_at": "2026-04-21T00:00:00.000000Z",
        "updated_at": "2026-04-21T00:00:00.000000Z"
      },
      "genres": [
        {
          "id": 1,
          "name": "Rock",
          "created_at": "2026-04-21T00:00:00.000000Z",
          "updated_at": "2026-04-21T00:00:00.000000Z",
          "pivot": {
            "track_id": 1,
            "genre_id": 1,
            "created_at": "2026-04-21T00:00:00.000000Z",
            "updated_at": "2026-04-21T00:00:00.000000Z"
          }
        }
      ]
    }
  ]
}

List All Albums

Request:

GET /api/albums
Authorization: Bearer {token}

Response (200 OK):

[
  {
    "id": 1,
    "title": "Abbey Road",
    "cover_path": "/images/abbey-road.jpg",
    "release_date": "1969-09-26T00:00:00.000000Z",
    "duration_seconds": 3025,
    "type": "album",
    "label_id": 1,
    "created_at": "2026-04-21T00:00:00.000000Z",
    "updated_at": "2026-04-21T00:00:00.000000Z",
    "label": {
      "id": 1,
      "name": "Universal Music",
      "created_at": "2026-04-21T00:00:00.000000Z",
      "updated_at": "2026-04-21T00:00:00.000000Z"
    }
  }
]

Get Single Album (with Relations)

Request:

GET /api/albums/1
Authorization: Bearer {token}

Response (200 OK):

{
  "id": 1,
  "title": "Abbey Road",
  "cover_path": "/images/abbey-road.jpg",
  "release_date": "1969-09-26T00:00:00.000000Z",
  "duration_seconds": 3025,
  "type": "album",
  "label_id": 1,
  "created_at": "2026-04-21T00:00:00.000000Z",
  "updated_at": "2026-04-21T00:00:00.000000Z",
  "label": {
    "id": 1,
    "name": "Universal Music",
    "created_at": "2026-04-21T00:00:00.000000Z",
    "updated_at": "2026-04-21T00:00:00.000000Z"
  },
  "tracks": [
    {
      "id": 1,
      "title": "Come Together",
      "file_path": "/music/come-together.mp3",
      "duration_seconds": 259,
      "album_id": 1,
      "created_at": "2026-04-21T00:00:00.000000Z",
      "updated_at": "2026-04-21T00:00:00.000000Z",
      "artists": [
        {
          "id": 1,
          "name": "The Beatles",
          "cover_path": "/images/beatles.jpg",
          "release_date": "1960-01-01T00:00:00.000000Z",
          "label_id": 1,
          "duration": null,
          "created_at": "2026-04-21T00:00:00.000000Z",
          "updated_at": "2026-04-21T00:00:00.000000Z",
          "pivot": {
            "track_id": 1,
            "artist_id": 1,
            "created_at": "2026-04-21T00:00:00.000000Z",
            "updated_at": "2026-04-21T00:00:00.000000Z"
          }
        }
      ],
      "genres": [
        {
          "id": 1,
          "name": "Rock",
          "created_at": "2026-04-21T00:00:00.000000Z",
          "updated_at": "2026-04-21T00:00:00.000000Z",
          "pivot": {
            "track_id": 1,
            "genre_id": 1,
            "created_at": "2026-04-21T00:00:00.000000Z",
            "updated_at": "2026-04-21T00:00:00.000000Z"
          }
        }
      ]
    }
  ]
}

List All Tracks

Request:

GET /api/tracks
Authorization: Bearer {token}

Response (200 OK):

[
  {
    "id": 1,
    "title": "Come Together",
    "file_path": "/music/come-together.mp3",
    "duration_seconds": 259,
    "album_id": 1,
    "created_at": "2026-04-21T00:00:00.000000Z",
    "updated_at": "2026-04-21T00:00:00.000000Z",
    "album": {
      "id": 1,
      "title": "Abbey Road",
      "cover_path": "/images/abbey-road.jpg",
      "release_date": "1969-09-26T00:00:00.000000Z",
      "duration_seconds": 3025,
      "type": "album",
      "label_id": 1,
      "created_at": "2026-04-21T00:00:00.000000Z",
      "updated_at": "2026-04-21T00:00:00.000000Z"
    },
    "artists": [
      {
        "id": 1,
        "name": "The Beatles",
        "cover_path": "/images/beatles.jpg",
        "release_date": "1960-01-01T00:00:00.000000Z",
        "label_id": 1,
        "duration": null,
        "created_at": "2026-04-21T00:00:00.000000Z",
        "updated_at": "2026-04-21T00:00:00.000000Z",
        "pivot": {
          "track_id": 1,
          "artist_id": 1,
          "created_at": "2026-04-21T00:00:00.000000Z",
          "updated_at": "2026-04-21T00:00:00.000000Z"
        }
      }
    ],
    "genres": [
      {
        "id": 1,
        "name": "Rock",
        "created_at": "2026-04-21T00:00:00.000000Z",
        "updated_at": "2026-04-21T00:00:00.000000Z",
        "pivot": {
          "track_id": 1,
          "genre_id": 1,
          "created_at": "2026-04-21T00:00:00.000000Z",
          "updated_at": "2026-04-21T00:00:00.000000Z"
        }
      }
    ]
  }
]

Get Single Track (with Relations)

Request:

GET /api/tracks/1
Authorization: Bearer {token}

Response (200 OK):

{
  "id": 1,
  "title": "Come Together",
  "file_path": "/music/come-together.mp3",
  "duration_seconds": 259,
  "album_id": 1,
  "created_at": "2026-04-21T00:00:00.000000Z",
  "updated_at": "2026-04-21T00:00:00.000000Z",
  "album": {
    "id": 1,
    "title": "Abbey Road",
    "cover_path": "/images/abbey-road.jpg",
    "release_date": "1969-09-26T00:00:00.000000Z",
    "duration_seconds": 3025,
    "type": "album",
    "label_id": 1,
    "created_at": "2026-04-21T00:00:00.000000Z",
    "updated_at": "2026-04-21T00:00:00.000000Z",
    "label": {
      "id": 1,
      "name": "Universal Music",
      "created_at": "2026-04-21T00:00:00.000000Z",
      "updated_at": "2026-04-21T00:00:00.000000Z"
    }
  },
  "artists": [
    {
      "id": 1,
      "name": "The Beatles",
      "cover_path": "/images/beatles.jpg",
      "release_date": "1960-01-01T00:00:00.000000Z",
      "label_id": 1,
      "duration": null,
      "created_at": "2026-04-21T00:00:00.000000Z",
      "updated_at": "2026-04-21T00:00:00.000000Z",
      "pivot": {
        "track_id": 1,
        "artist_id": 1,
        "created_at": "2026-04-21T00:00:00.000000Z",
        "updated_at": "2026-04-21T00:00:00.000000Z"
      }
    }
  ],
  "genres": [
    {
      "id": 1,
      "name": "Rock",
      "created_at": "2026-04-21T00:00:00.000000Z",
      "updated_at": "2026-04-21T00:00:00.000000Z",
      "pivot": {
        "track_id": 1,
        "genre_id": 1,
        "created_at": "2026-04-21T00:00:00.000000Z",
        "updated_at": "2026-04-21T00:00:00.000000Z"
      }
    }
  ]
}

3. User Likes/Favorites

Get User's Liked Tracks

Request:

GET /api/me/likes
Authorization: Bearer {token}

Response (200 OK):

[
  {
    "id": 1,
    "title": "Come Together",
    "file_path": "/music/come-together.mp3",
    "duration_seconds": 259,
    "album_id": 1,
    "created_at": "2026-04-21T00:00:00.000000Z",
    "updated_at": "2026-04-21T00:00:00.000000Z",
    "album": { ... },
    "artists": [ ... ],
    "genres": [ ... ]
  }
]

Like a Track

Request:

POST /api/tracks/1/like
Authorization: Bearer {token}

Response (200 OK):

{
  "message": "Track liked."
}

Unlike a Track

Request:

DELETE /api/tracks/1/like
Authorization: Bearer {token}

Response (200 OK):

{
  "message": "Track unliked."
}

4. Admin CRUD Operations

Create Label (Admin Only)

Request:

POST /api/labels
Authorization: Bearer {admin_token}
Content-Type: application/json

{
  "name": "Epic Records"
}

Response (201 Created):

{
  "id": 3,
  "name": "Epic Records",
  "created_at": "2026-05-07T10:10:00.000000Z",
  "updated_at": "2026-05-07T10:10:00.000000Z"
}

Update Label (Admin Only)

Request:

PUT /api/labels/3
Authorization: Bearer {admin_token}
Content-Type: application/json

{
  "name": "Epic Records Group"
}

Response (200 OK):

{
  "id": 3,
  "name": "Epic Records Group",
  "created_at": "2026-05-07T10:10:00.000000Z",
  "updated_at": "2026-05-07T10:15:00.000000Z"
}

Delete Label (Admin Only)

Request:

DELETE /api/labels/3
Authorization: Bearer {admin_token}

Response (204 No Content):

(Empty body)

Create Genre (Admin Only)

Request:

POST /api/genres
Authorization: Bearer {admin_token}
Content-Type: application/json

{
  "name": "Jazz"
}

Response (201 Created):

{
  "id": 3,
  "name": "Jazz",
  "created_at": "2026-05-07T10:10:00.000000Z",
  "updated_at": "2026-05-07T10:10:00.000000Z"
}

Create Artist (Admin Only)

Request:

POST /api/artists
Authorization: Bearer {admin_token}
Content-Type: application/json

{
  "name": "Miles Davis",
  "cover_path": "/images/miles-davis.jpg",
  "release_date": "1926-05-26",
  "label_id": 1,
  "duration": null
}

Response (201 Created):

{
  "id": 2,
  "name": "Miles Davis",
  "cover_path": "/images/miles-davis.jpg",
  "release_date": "1926-05-26T00:00:00.000000Z",
  "label_id": 1,
  "duration": null,
  "created_at": "2026-05-07T10:10:00.000000Z",
  "updated_at": "2026-05-07T10:10:00.000000Z",
  "label": {
    "id": 1,
    "name": "Universal Music",
    "created_at": "2026-04-21T00:00:00.000000Z",
    "updated_at": "2026-04-21T00:00:00.000000Z"
  }
}

Create Album (Admin Only)

Request:

POST /api/albums
Authorization: Bearer {admin_token}
Content-Type: application/json

{
  "title": "Kind of Blue",
  "cover_path": "/images/kind-of-blue.jpg",
  "release_date": "1959-03-02",
  "duration_seconds": 1975,
  "type": "album",
  "label_id": 1
}

Response (201 Created):

{
  "id": 2,
  "title": "Kind of Blue",
  "cover_path": "/images/kind-of-blue.jpg",
  "release_date": "1959-03-02T00:00:00.000000Z",
  "duration_seconds": 1975,
  "type": "album",
  "label_id": 1,
  "created_at": "2026-05-07T10:10:00.000000Z",
  "updated_at": "2026-05-07T10:10:00.000000Z",
  "label": {
    "id": 1,
    "name": "Universal Music",
    "created_at": "2026-04-21T00:00:00.000000Z",
    "updated_at": "2026-04-21T00:00:00.000000Z"
  }
}

Create Track (Admin Only)

Request:

POST /api/tracks
Authorization: Bearer {admin_token}
Content-Type: application/json

{
  "title": "So What",
  "file_path": "/music/so-what.mp3",
  "duration_seconds": 567,
  "album_id": 2,
  "artist_ids": [2],
  "genre_ids": [3]
}

Response (201 Created):

{
  "id": 2,
  "title": "So What",
  "file_path": "/music/so-what.mp3",
  "duration_seconds": 567,
  "album_id": 2,
  "created_at": "2026-05-07T10:10:00.000000Z",
  "updated_at": "2026-05-07T10:10:00.000000Z",
  "album": {
    "id": 2,
    "title": "Kind of Blue",
    "cover_path": "/images/kind-of-blue.jpg",
    "release_date": "1959-03-02T00:00:00.000000Z",
    "duration_seconds": 1975,
    "type": "album",
    "label_id": 1,
    "created_at": "2026-05-07T10:10:00.000000Z",
    "updated_at": "2026-05-07T10:10:00.000000Z"
  },
  "artists": [
    {
      "id": 2,
      "name": "Miles Davis",
      "cover_path": "/images/miles-davis.jpg",
      "release_date": "1926-05-26T00:00:00.000000Z",
      "label_id": 1,
      "duration": null,
      "created_at": "2026-05-07T10:10:00.000000Z",
      "updated_at": "2026-05-07T10:10:00.000000Z",
      "pivot": {
        "track_id": 2,
        "artist_id": 2,
        "created_at": "2026-05-07T10:10:00.000000Z",
        "updated_at": "2026-05-07T10:10:00.000000Z"
      }
    }
  ],
  "genres": [
    {
      "id": 3,
      "name": "Jazz",
      "created_at": "2026-05-07T10:10:00.000000Z",
      "updated_at": "2026-05-07T10:10:00.000000Z",
      "pivot": {
        "track_id": 2,
        "genre_id": 3,
        "created_at": "2026-05-07T10:10:00.000000Z",
        "updated_at": "2026-05-07T10:10:00.000000Z"
      }
    }
  ]
}

Update Track (Admin Only)

Request:

PUT /api/tracks/2
Authorization: Bearer {admin_token}
Content-Type: application/json

{
  "title": "So What (Remastered)",
  "artist_ids": [2],
  "genre_ids": [1, 3]
}

Response (200 OK):

{
  "id": 2,
  "title": "So What (Remastered)",
  "file_path": "/music/so-what.mp3",
  "duration_seconds": 567,
  "album_id": 2,
  "created_at": "2026-05-07T10:10:00.000000Z",
  "updated_at": "2026-05-07T10:20:00.000000Z",
  "album": { ... },
  "artists": [ ... ],
  "genres": [
    { "id": 1, "name": "Rock", ... },
    { "id": 3, "name": "Jazz", ... }
  ]
}

Delete Track (Admin Only)

Request:

DELETE /api/tracks/2
Authorization: Bearer {admin_token}

Response (204 No Content):

(Empty body)

List All Users (Admin Only)

Request:

GET /api/users
Authorization: Bearer {admin_token}

Response (200 OK):

[
  {
    "id": 1,
    "name": "John Doe",
    "email": "john@example.com",
    "role_id": 2,
    "created_at": "2026-05-07T10:05:00.000000Z",
    "updated_at": "2026-05-07T10:05:00.000000Z",
    "role": {
      "id": 2,
      "name": "user",
      "created_at": "2026-04-21T00:00:00.000000Z",
      "updated_at": "2026-04-21T00:00:00.000000Z"
    }
  }
]

Get Single User (Admin Only)

Request:

GET /api/users/1
Authorization: Bearer {admin_token}

Response (200 OK):

{
  "id": 1,
  "name": "John Doe",
  "email": "john@example.com",
  "role_id": 2,
  "created_at": "2026-05-07T10:05:00.000000Z",
  "updated_at": "2026-05-07T10:05:00.000000Z",
  "role": {
    "id": 2,
    "name": "user",
    "created_at": "2026-04-21T00:00:00.000000Z",
    "updated_at": "2026-04-21T00:00:00.000000Z"
  }
}

Update User (Admin Only)

Request:

PUT /api/users/1
Authorization: Bearer {admin_token}
Content-Type: application/json

{
  "name": "Jane Doe",
  "email": "jane@example.com",
  "role_id": 1
}

Response (200 OK):

{
  "id": 1,
  "name": "Jane Doe",
  "email": "jane@example.com",
  "role_id": 1,
  "created_at": "2026-05-07T10:05:00.000000Z",
  "updated_at": "2026-05-07T10:25:00.000000Z",
  "role": {
    "id": 1,
    "name": "admin",
    "created_at": "2026-04-21T00:00:00.000000Z",
    "updated_at": "2026-04-21T00:00:00.000000Z"
  }
}

Delete User (Admin Only)

Request:

DELETE /api/users/1
Authorization: Bearer {admin_token}

Response (204 No Content):

(Empty body)

5. Error Responses

Validation Error (400 Bad Request)

Response:

{
  "message": "The given data was invalid.",
  "errors": {
    "email": ["The email has already been taken."],
    "password": ["The password must be at least 8 characters."]
  }
}

Authentication Error (401 Unauthorized)

Response:

{
  "message": "Unauthenticated."
}

Authorization Error (403 Forbidden - User trying to access Admin endpoint)

Response:

{
  "message": "Forbidden."
}

Not Found Error (404)

Response:

{
  "message": "No query results found for model [App\\Models\\Track] 999"
}

Login Invalid Credentials (422 Unprocessable Content)

Response:

{
  "message": "The given data was invalid.",
  "errors": {
    "email": ["The provided credentials are incorrect."]
  }
}

6. Headers

Required Headers

Authorization: Bearer {token}
Content-Type: application/json (for POST/PUT requests)

Example with cURL

curl -X GET http://localhost/api/tracks \
  -H "Authorization: Bearer 1|abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890" \
  -H "Content-Type: application/json"

7. HTTP Status Codes

Code Meaning Example
200 OK Successful GET/POST/PUT
201 Created Successful resource creation
204 No Content Successful DELETE
400 Bad Request Validation error
401 Unauthorized Missing/invalid token
403 Forbidden Admin-only endpoint + user role
404 Not Found Resource doesn't exist
422 Unprocessable Content Login with wrong credentials
Reference in New Issue View Git Blame Copy Permalink