Composers API Documentation

Documentation for the Composers REST API endpoint.

Endpoints

GET /api/v1/libraries/{library_id}/composers

Retrieve a list of composers for a specific library.

Path Parameters

Name Type Description Required
library_id integer ID of the library Yes

Query Parameters

Name Type Description
page integer Page number for pagination (default: 1)

Response

{
    "pagination": {
        "total_entries": 10523,
        "per_page": 5,
        "current_page": 1,
        "total_pages": 421,
        "next_page": 2,
        "next_page_url": "http://127.0.0.1:3000/api/v1/libraries/2/composers?page=2"
    },
    "composers": [
        {
            "id": 1,
            "library_id": 2,
            "name": "Ilze E. Platais",
            "birth_date": null,
            "death_date": null,
            "pro_id": 10,
            "ipi_number": 49448942,
            "created_at": "2024-08-19T13:30:26.166-05:00",
            "updated_at": "2024-08-19T13:36:56.251-05:00",
            "url": "http://127.0.0.1:3000/api/v1/libraries/2/composers/1"
        },
        {
            "id": 2,
            "library_id": 2,
            "name": "Neal Busby",
            "birth_date": null,
            "death_date": null,
            "pro_id": 101,
            "ipi_number": 229835933,
            "created_at": "2024-08-19T13:36:56.263-05:00",
            "updated_at": "2024-08-19T13:36:56.263-05:00",
            "url": "http://127.0.0.1:3000/api/v1/libraries/2/composers/2"
        }
    ]
}

Response Fields

Field Type Description
pagination object Contains pagination information
composers array List of composer objects
id integer Unique identifier for the composer
library_id integer ID of the library the composer belongs to
name string Name of the composer
birth_date string | null Birth date of the composer (if available)
death_date string | null Death date of the composer (if applicable)
pro_id integer Society code of the composer
ipi_number integer IPI (Interested Parties Information) number
created_at string Timestamp of when the composer was created
updated_at string Timestamp of when the composer was last updated
url string URL to access the individual composer’s details

HTTP Response Codes

Code Description
200 OK Successful request
404 Not Found Invalid library ID

POST /api/v1/composers

Create a new composer.

Request Body

Field Type Description Required
external_id integer Unique identifier for the composer Yes
name string Name of the composer Yes
birth_date string (YYYY-MM-DD) Birth date of the composer No
death_date string (YYYY-MM-DD) Death date of the composer (if applicable) No
pro_id string Society code of the composer No
ipi_number string IPI (Interested Parties Information) number No

Response

{
    "data": {
        "external_id": 125,
        "name": "Johann Sebastian Bach",
        "birth_date": "1685-03-31",
        "death_date": "1750-07-28",
        "pro_id": "GEMA",
        "ipi_number": "00000000116"
    }
}

HTTP Response Codes

Code Description
201 Created Successful request
404 Not Found Invalid library ID
422 Unprocessable Entity Invalid request (see response body for details)

GET /api/v1/libraries/{library_id}/composers/{id}

Retrieve details of a specific composer.

Path Parameters

Name Type Description Required
library_id integer ID of the library Yes
id integer ID of the composer Yes

Response

{
    "id": 1,
    "library_id": 2,
    "name": "Ilze E. Platais",
    "birth_date": null,
    "death_date": null,
    "pro_id": 10,
    "ipi_number": 49448942,
    "created_at": "2024-08-19T13:30:26.166-05:00",
    "updated_at": "2024-08-19T13:36:56.251-05:00",
    "url": "http://127.0.0.1:3000/api/v1/libraries/2/composers/1"
}

HTTP Response Codes

Code Description
200 OK Successful request
404 Not Found Invalid library ID

PUT /api/v1/libraries/{library_id}/composers/{id}

Update details of a specific composer.

Path Parameters

Name Type Description Required
library_id integer ID of the library Yes
id integer ID of the composer Yes

Request Body

{
    "name": "Updated Composer Name",
    "birth_date": "1990-01-01",
    "death_date": null,
    "pro_id": 20,
    "ipi_number": 123456789
}

Response

{
    "id": 1,
    "library_id": 2,
    "name": "Updated Composer Name",
    "birth_date": "1990-01-01",
    "death_date": null,
    "pro_id": 20,
    "ipi_number": 123456789,
    "created_at": "2024-08-19T13:30:26.166-05:00",
    "updated_at": "2024-08-20T10:15:30.123-05:00",
    "url": "http://127.0.0.1:3000/api/v1/libraries/2/composers/1"
}

HTTP Response Codes

Code Description
200 OK Successful request
404 Not Found Invalid library ID or composer ID
422 Unprocessable Entity Invalid request (see response body for details)

DELETE /api/v1/libraries/{library_id}/composers/{id}

Delete a specific composer.

Path Parameters

Name Type Description Required
library_id integer ID of the library Yes
id integer ID of the composer Yes

Response

(no response body)

HTTP Response Codes

Code Description
204 No Content Successful request
404 Not Found Invalid library ID or composer ID