API Reference - Jazz Reference API Documentation

Songs

GET /api/songs

Get all songs or search songs by title or composer

Query Parameters

Parameter	Type	Required	Description
`search`	string	No	Search query to filter songs by title or composer (case-insensitive)

Response (200 OK)

JSON

[
  {
    "id": 1,
    "title": "Take Five",
    "composer": "Paul Desmond",
    "structure": "AABA in Eb minor",
    "musicbrainz_id": "abc123",
    "song_reference": "Dave Brubeck Quartet recording",
    "external_references": {
      "wikipedia": "https://en.wikipedia.org/wiki/Take_Five"
    },
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
]

Example Requests

cURL

# Get all songs
curl https://www.linernotesjazz.com/api/songs

# Search for songs
curl "https://www.linernotesjazz.com/api/songs?search=blue"

GET /api/songs/<song_id>

Get detailed information about a specific song

Path Parameters

Parameter	Type	Description
`song_id`	integer	The unique identifier of the song

Response (200 OK)

JSON

{
  "id": 1,
  "title": "Take Five",
  "composer": "Paul Desmond",
  "structure": "AABA in Eb minor",
  "musicbrainz_id": "abc123",
  "song_reference": "Dave Brubeck Quartet recording",
  "external_references": {
    "wikipedia": "https://en.wikipedia.org/wiki/Take_Five"
  },
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Example Request

cURL

curl https://www.linernotesjazz.com/api/songs/1

Error Response (404 Not Found)

JSON

{
  "error": "Song not found"
}

GET /api/songs/<song_id>/recordings

Get all recordings of a specific song

Path Parameters

Parameter	Type	Description
`song_id`	integer	The unique identifier of the song

Response (200 OK)

JSON

[
  {
    "id": 1,
    "song_id": 1,
    "album_title": "Time Out",
    "recording_date": "1959-07-01",
    "label": "Columbia Records",
    "musicbrainz_id": "xyz789",
    "spotify_url": "spotify:track:...",
    "youtube_url": "https://youtube.com/watch?v=...",
    "is_canonical": true,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
]

Example Request

cURL

curl https://www.linernotesjazz.com/api/songs/1/recordings

Recordings

GET /api/recordings

Get all recordings or search by album title

Query Parameters

Parameter	Type	Required	Description
`search`	string	No	Search query to filter recordings by album title

Response (200 OK)

JSON

[
  {
    "id": 1,
    "song_id": 1,
    "album_title": "Time Out",
    "recording_date": "1959-07-01",
    "label": "Columbia Records",
    "musicbrainz_id": "xyz789",
    "spotify_url": "spotify:track:...",
    "youtube_url": "https://youtube.com/watch?v=...",
    "is_canonical": true,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
]

Example Request

cURL

curl "https://www.linernotesjazz.com/api/recordings?search=time%20out"

GET /api/recordings/<recording_id>

Get detailed information about a specific recording with full performer lineup

Path Parameters

Parameter	Type	Description
`recording_id`	integer	The unique identifier of the recording

Response (200 OK)

JSON

{
  "recording": {
    "id": 1,
    "song_id": 1,
    "song_title": "Take Five",
    "album_title": "Time Out",
    "recording_date": "1959-07-01",
    "label": "Columbia Records",
    "spotify_url": "spotify:track:...",
    "youtube_url": "https://youtube.com/watch?v=...",
    "is_canonical": true
  },
  "performers": [
    {
      "performer_id": 1,
      "name": "Dave Brubeck",
      "instrument": "Piano"
    },
    {
      "performer_id": 2,
      "name": "Paul Desmond",
      "instrument": "Alto Saxophone"
    }
  ]
}

Example Request

cURL

curl https://www.linernotesjazz.com/api/recordings/1

Performers

GET /api/performers

Get all performers or search by name

Query Parameters

Parameter	Type	Required	Description
`search`	string	No	Search query to filter performers by name

Response (200 OK)

JSON

[
  {
    "id": 1,
    "name": "Miles Davis",
    "biography": "Miles Dewey Davis III was an American jazz...",
    "birth_date": "1926-05-26",
    "death_date": "1991-09-28",
    "external_links": {
      "wikipedia": "https://en.wikipedia.org/wiki/Miles_Davis"
    }
  }
]

Example Request

cURL

curl "https://www.linernotesjazz.com/api/performers?search=miles"

GET /api/performers/<performer_id>

Get detailed information about a specific performer with their complete discography

Path Parameters

Parameter	Type	Description
`performer_id`	integer	The unique identifier of the performer

Response (200 OK)

JSON

{
  "performer": {
    "id": 1,
    "name": "Miles Davis",
    "biography": "Miles Dewey Davis III was an American jazz...",
    "birth_date": "1926-05-26",
    "death_date": "1991-09-28",
    "external_links": {
      "wikipedia": "https://en.wikipedia.org/wiki/Miles_Davis"
    }
  },
  "recordings": [
    {
      "recording_id": 5,
      "song_title": "So What",
      "album_title": "Kind of Blue",
      "recording_date": "1959-03-02",
      "instrument": "Trumpet"
    }
  ]
}

Example Request

cURL

curl https://www.linernotesjazz.com/api/performers/1

GET /api/performers/<performer_id>/images

Get all images for a specific performer

Path Parameters

Parameter	Type	Description
`performer_id`	integer	The unique identifier of the performer

Response (200 OK)

JSON

[
  {
    "id": 1,
    "url": "https://example.com/image.jpg",
    "source": "Wikimedia Commons",
    "source_identifier": "File:Miles_Davis.jpg",
    "license_type": "CC BY-SA 3.0",
    "license_url": "https://creativecommons.org/licenses/by-sa/3.0/",
    "attribution": "Photo by Tom Marcello",
    "width": 1024,
    "height": 768,
    "thumbnail_url": "https://example.com/image_thumb.jpg",
    "source_page_url": "https://commons.wikimedia.org/wiki/File:Miles_Davis.jpg",
    "is_primary": true,
    "display_order": 1
  }
]

Example Request

cURL

curl https://www.linernotesjazz.com/api/performers/1/images

Images

GET /api/images/<image_id>

Get detailed information about a specific image

Path Parameters

Parameter	Type	Description
`image_id`	integer	The unique identifier of the image

Response (200 OK)

JSON

{
  "id": 1,
  "url": "https://example.com/image.jpg",
  "source": "Wikimedia Commons",
  "source_identifier": "File:Miles_Davis.jpg",
  "license_type": "CC BY-SA 3.0",
  "license_url": "https://creativecommons.org/licenses/by-sa/3.0/",
  "attribution": "Photo by Tom Marcello",
  "width": 1024,
  "height": 768,
  "thumbnail_url": "https://example.com/image_thumb.jpg",
  "source_page_url": "https://commons.wikimedia.org/wiki/File:Miles_Davis.jpg",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

Example Request

cURL

curl https://www.linernotesjazz.com/api/images/1

Health Check

GET /api/health

Check the health status of the API and database connection

Response (200 OK)

JSON

{
  "status": "healthy",
  "database": "connected",
  "pool_stats": {
    "pool_size": 5,
    "pool_available": 4,
    "requests_waiting": 0
  },
  "timestamp": 1705320600.123,
  "db_version": "PostgreSQL 15.1",
  "db_time": "2024-01-15 10:30:00"
}

Response (503 Service Unavailable)

JSON

{
  "status": "unhealthy",
  "database": "error: connection timeout",
  "timestamp": 1705320600.123
}

Example Request

cURL

curl https://www.linernotesjazz.com/api/health