Books
Books are used to organize large libraries of songs into collections.
List books
| URL | /api/<auth_token>/books |
| Method | GET |
| Version | 1.0 |
Description
Lists books in your OnSong library.
Path arguments
| Name | Type | Description | Required |
|---|---|---|---|
| auth_token | string | The authentication token used to authenticate the request. | Required |
Query arguments
Options for searching are passed via the query string as follows:
/api/<auth_token>/books?q=sample&sort=title
| Name | Type | Description | Required |
|---|---|---|---|
| q | string | The query to look up books by title | Optional |
| sort | string |
The sort method to use when returning sets. Options include:
|
Optional |
| descending | boolean | Determines if sets should be returned in descending order. The default order is set by the sort method. | Optional |
| limit | number | Limits the number of results returned. Default is 100. | Optional |
| start | number | Offsets the start of returned results to be used for paging through results. Default is 0. | Optional |
Response
Returns a list of sets in the OnSong library including the set's unique identifier, title and quantity of songs in the set.
Response example
{
"count" : 1,
"results" : [
{
"ID" : "Sample Book",
"name" : "Sample Book"
}
],
"attributes" : {
"q" : "sample",
"sort" : "title"
}
}
Create book
| URL | /api/<auth_token>/books |
| Method | PUT |
| Version | 1.0 |
Description
Creates a new book in your library.
Path arguments
| Name | Type | Description | Required |
|---|---|---|---|
| auth_token | string | The authentication token used to authenticate the request. | Required |
Body arguments
| Name | Type | Description | Required |
|---|---|---|---|
| name | string | The name of the book to create. | Required |
| songs | array | An array of song identifiers to add to the book. | Optional |
Response
One of two results will be returned:
| Name | Type | Description |
|---|---|---|
| success | object | The operation was successful and basic set information is returned. |
| error | string | The operation has failed and text indicating the error is returned. |
Response example
The following is an example of a successful creation:
{
"success" : {
"ID" : "Christmas Carols",
"name" : "Christmas Carols"
}
}
The following is an example of a failed operation with a 500 status code:
{
"error" : "Name is required"
}
View book information
| URL | /api/<auth_token>/books/<book_identifier> |
| Method | GET |
| Version | 1.0 |
Description
Retrieves book information from the OnSong library.
Path arguments
| Name | Type | Description | Required |
|---|---|---|---|
| auth_token | string | The authentication token used to authenticate the request. | Required |
| book_identifier | string | The name of the book to be retrieved. This can be the name of the book to be retrieved or the term "current" to use the currently active book. | Required |
Query arguments
| Name | Type | Description | Required |
|---|---|---|---|
| show_songs | boolean | Determines if songs should be displayed using the "songs" property. | Optional |
Response
| Name | Type | Description |
|---|---|---|
| ID | string | The unique identifier of the book. |
| name | string | The name of the book. |
| songs | array | The list of songs that are in the set sorted in custom order. |
Response example
The response does not include NULL values.
{
"ID" : "Sample",
"name" : "Sample",
"songs" : [
{
"ID" : "ADC7622D-EF15-4EA0-9DC0-A8E086F8D8A3",
"title" : "Oceans (Where Feet May Fail)",
"favorite" : 0,
"usefile" : false,
"key" : "D",
"artist" : "Hillsong United"
}
]
}
Update book
| URL | /api/<auth_token>/books/<set_identifier> |
| Method | POST |
| Version | 1.0 |
Description
Updates a book in your library.
Path arguments
| Name | Type | Description | Required |
|---|---|---|---|
| auth_token | string | The authentication token used to authenticate the request. | Required |
Body arguments
If arguments are not provided, no changes will be made to that set property.
| Name | Type | Description | Required |
|---|---|---|---|
| name | string | The name of the set. | Optional |
| songs | array | An array of song identifiers in the preferred order. | Optional |
Response
Returns an array of status updates for each property that has been updated.
| Name | Type | Description |
|---|---|---|
| success | object | The operation was successful and basic set information is returned. |
| error | string | The operation has failed and text indicating the error is returned. |
Response example
The following is an example of a successful update:
[
{
"success" : { "/books/837BB846-F374-4369-86ED-2A1A08EE131B/name" : "Party Songs" }
},
{
"success" : { "/books/837BB846-F374-4369-86ED-2A1A08EE131B/songs" : [ "837BB846-F374-4369-86FF-2A1A08EE131B", "837BB846-F374-4369-86FE-2A1A08EE131B" ] }
}
]
The following is an example of a failed operation with a 500 status code:
{
"error" : "Input must be a dictionary object"
}
Delete book
| URL | /api/<auth_token>/books/<book_identifier> |
| Method | DELETE |
| Version | 1.0 |
Description
Deletes a book from your library.
Path arguments
| Name | Type | Description | Required |
|---|---|---|---|
| auth_token | string | The authentication token used to authenticate the request. | Required |
Response
| Name | Type | Description |
|---|---|---|
| success | object | The operation was successful and basic set information is returned. |
| error | string | The operation has failed and text indicating the error is returned. |
Response example
The following is an example of a successful deletion:
{
"success" : { "ID" : "837BB846-F374-4369-86ED-2A1A08EE131B", "name" : "Deleted Book" }
}
The following is an example of a failed operation with a 500 status code:
{
"error" : "No book found"
}