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" }