Sets
Sets are used to pull songs and place in a specific order for playing events.
Find sets
URL | /api/<auth_token>/sets |
Method | GET |
Version | 1.0 |
Description
Finds and lists sets 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>/sets?q=welcome&limit=10&sort=title
Name | Type | Description | Required |
---|---|---|---|
q | string | The query to look up sets by title | Optional |
archived | boolean | Determines if archived sets should be returned. If not specified, all sets are returned. | 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
{ "attributes" : { "q" : "welcome", "start" : "0", "limit" : "2" }, "count" : 1, "results" : [ { "ID" : "welcome_to_song", "title" : "Welcome", "quantity" : 1 } ] }
Create set
URL | /api/<auth_token>/sets |
Method | PUT |
Version | 1.0 |
Description
Creates a new set 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 |
---|---|---|---|
title | string | The title of the set. | Optional |
summary | string | The summary of the set. | Optional |
datetime | date | The date of the set. Passed as a string in the ISO8601. | Optional |
expires | date | The expiration date for the set to expire. Passed as a string in the ISO8601. | Optional |
songs | array | An array of song identifiers in the preferred order. | 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 update:
{ "success" : { "ID" : "837BB846-F374-4369-86ED-2A1A08EE131B", "title" : "New Set" "datetime" : "2013-12-04T07:39:00+05:00" } }
The following is an example of a failed operation with a 500 status code:
{ "error" : "Input must be a dictionary object" }
View set information
URL | /api/<auth_token>/sets/<set_identifier> |
Method | GET |
Version | 1.0 |
Description
Retrieves set information from the OnSong library.
Path arguments
Name | Type | Description | Required |
---|---|---|---|
auth_token | string | The authentication token used to authenticate the request. | Required |
set_identifier | string | The song identifier of the set information to be retrieved. This can be the identifier of a set, or the term "current" which is the set currently being viewed. | Required |
Query arguments
Name | Type | Description | Required |
---|---|---|---|
show_songs | boolean | Determines if songs should be displayed using the "songs" property. | Optional |
Response
Returns a Set Object.
Response example
The response does not include NULL values.
{ "modified" : "2010-06-20T17:14:58-04:00", "user" : "87b7d2eededcd0f408ee4de1bfe8f42b300e47d6", "orderMethod" : "orderIndex", "quantity" : 1, "created" : "1969-12-31T19:00:00-05:00", "ID" : "welcome_to_song", "title" : "Welcome" }
Retrieve set content
URL | /api/<auth_token>/sets/<set_identifier>/content(.format) |
Method | GET |
Version | 1.0 |
Description
Retrieves set information from the OnSong library.
Path arguments
Name | Type | Description | Required |
---|---|---|---|
auth_token | string | The authentication token used to authenticate the request. | Required |
set_identifier | string | The identifier of the set information to be retrieved. This can be the identifier of a set, or the term "current" which is the set currently being viewed. | Required |
format | string | The format to use when returning content. Options include:
|
Optional |
Response
Returns the content of the set.
Update set
URL | /api/<auth_token>/sets/<set_identifier> |
Method | POST |
Version | 1.0 |
Description
Updates a set 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 |
---|---|---|---|
title | string | The title of the set. | Optional |
summary | string | The summary of the set. | Optional |
datetime | date | The date of the set. Passed as a string in the ISO8601 format. | Optional |
expires | date | The expiration date for the set to expire. Passed as a string in the ISO8601 format. | Optional |
archived | date | The date when the set is to be archived. Passed as a string in the ISO8601 format. | Optional |
songs | array | An array of song identifiers in the preferred order. If songs are already in the set, they are moved. Otherwise the song is loaded and added to the set. If the song is omitted from this list, it is removed from the set. | 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" : { "/sets/837BB846-F374-4369-86ED-2A1A08EE131B/title" : "New Title" } }, { "success" : { "/sets/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 set
URL | /api/<auth_token>/sets/<set_identifier> |
Method | DELETE |
Version | 1.0 |
Description
Deletes a set from your library.
Path arguments
Name | Type | Description | Required |
---|---|---|---|
auth_token | string | The authentication token used to authenticate the request. | Required |
set_identifier | string | The identifier of the set to be deleted. | 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", "title" : "Deleted Set" } }
The following is an example of a failed operation with a 500 status code:
{ "error" : "No set found" }