🎤 Artists

Artist management for album and track associations with smart duplicate prevention

Resource Overview

Artists represent individual performers, bands, or musical entities. The system implements intelligent find-or-create logic to prevent duplicate artists for the same user.

Base Endpoint
/artists
Resource Type
artists
User Scope
Owner-restricted

Smart Artist Creation

The API automatically prevents duplicate artists. If an artist with the same name already exists for the user, the system returns the existing artist instead of creating a duplicate, ensuring data consistency.

Schema

Required Attributes

Field Type Validation Description
name string required, max:255 Artist name

Optional Attributes

Field Type Validation Description
bio string nullable Artist biography or description

Read-only Attributes

Field Type Description
id string Unique identifier
created-at datetime Creation timestamp
updated-at datetime Last update timestamp

Relationships

Relationship Type Related Resource Description Editable
album-artists HasMany album-artists Album associations with artist roles ❌

List Artists

GET /artists 
GET /artists
Authorization: Bearer {token}
Accept: application/vnd.api+json

Query Parameters

Filtering

  • • filter[name] - Filter by artist name
  • • filter[bio] - Search in biography
  • • filter[created-at] - Filter by creation date

Other Parameters

  • • include - Include related resources
  • • sort - Sort by field
  • • page[number] - Page number
  • • page[size] - Results per page

Success Response

200 OK 
{
  "data": [
    {
      "type": "artists",
      "id": "1",
      "attributes": {
        "name": "John Smith",
        "bio": "Singer-songwriter from Nashville",
        "created-at": "2024-01-01T10:00:00Z",
        "updated-at": "2024-01-01T10:00:00Z"
      },
      "relationships": {
        "album-artists": {
          "data": [
            { "type": "album-artists", "id": "1" },
            { "type": "album-artists", "id": "2" }
          ]
        }
      }
    }
  ],
  "meta": {
    "page": {
      "current-page": 1,
      "per-page": 20,
      "total": 25,
      "last-page": 2
    }
  }
}

Create Artist

POST /artists 
{
  "data": {
    "type": "artists",
    "attributes": {
      "name": "New Artist",
      "bio": "Emerging artist with unique sound"
    }
  }
}

Smart Creation Logic

Find-or-Create Behavior

If artist exists: Returns existing artist, optionally updates bio if provided

If artist doesn't exist: Creates new artist with provided data

Matching criteria: Same name + same owner user

Success Response

201 Created 
{
  "data": {
    "type": "artists",
    "id": "42",
    "attributes": {
      "name": "New Artist",
      "bio": "Emerging artist with unique sound",
      "created-at": "2024-08-19T10:00:00Z",
      "updated-at": "2024-08-19T10:00:00Z"
    }
  }
}

Existing Artist Response

If an artist with the same name already exists:

200 OK 
{
  "data": {
    "type": "artists",
    "id": "15",
    "attributes": {
      "name": "Existing Artist",
      "bio": "Updated bio if provided",
      "created-at": "2024-01-01T10:00:00Z",
      "updated-at": "2024-08-19T10:00:00Z"
    }
  }
}

Update Artist

PATCH /artists/{id} 
{
  "data": {
    "type": "artists",
    "id": "1",
    "attributes": {
      "name": "Updated Artist Name",
      "bio": "Updated biography with more details"
    }
  }
}

Success Response

200 OK 
{
  "data": {
    "type": "artists",
    "id": "1",
    "attributes": {
      "name": "Updated Artist Name",
      "bio": "Updated biography with more details",
      "updated-at": "2024-08-19T10:15:00Z"
    }
  }
}

Delete Artist

DELETE /artists/{id} 
DELETE /artists/1
Authorization: Bearer {token}

⚠️ Dependency Check

Artists with existing album associations cannot be deleted. Remove all album-artist relationships first.

Success Response

204 No Content

💡 Usage Examples

Bulk Artist Creation

Create multiple artists without worrying about duplicates:

const artists = ['John Smith', 'Jane Doe', 'John Smith'];

for (const name of artists) {
  await fetch('/artists', {
    method: 'POST',
    body: JSON.stringify({
      data: { type: 'artists', attributes: { name } }
    })
  });
}
// John Smith will only be created once

Search Artists

Find artists by name or bio content:

Search by name
GET /artists?filter[name]=john
Search in bio
GET /artists?filter[bio]=singer
Include album associations
GET /artists?include=album-artists

🚀 Best Practices

🎯 Data Quality

  • • Use consistent naming conventions
  • • Provide meaningful biographies
  • • Avoid special characters in names
  • • Check for existing artists before creation
  • • Update bios when adding new artists

⚡ Performance

  • • Use the smart creation feature to prevent duplicates
  • • Include relationships when needed
  • • Filter by name for better search performance
  • • Paginate large artist lists
  • • Cache frequently accessed artist data