Folders
Folders are used to organize sets for specific venues or other organization methods.
Find folders
| URL | /api/<auth_token>/folders |
| Method | GET |
| Version | 1.0 |
Description
Finds and lists folders 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>/folders?q=welcome&limit=10&sort=title
| Name | Type | Description | Required |
|---|---|---|---|
| q | string | The query to look up folders by title | Optional |
| sort | string |
The sort method to use when returning folders. Options include:
|
Optional |
| descending | boolean | Determines if folders 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 folders in the OnSong library including the folder's unique identifier, title and quantity of sets in the folder.
Response example
{
"attributes" : {
"q" : "welcome",
"start" : "0",
"limit" : "2"
},
"count" : 1,
"results" : [
{
"ID" : "7C55CC6B-1BED-4D42-9517-3D600C5BEC77",
"title" : "Carly's Pub",
"quantity" : 1
}
]
}
Create folder
| URL | /api/<auth_token>/folders |
| Method | PUT |
| Version | 1.0 |
Description
Creates a new folder 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 folder. | Required |
| orderMethod | string | The order method to use when sorting sets within the folder. Valid options include title or orderIndex. | Optional |
| sets | array | An array of set 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 folder 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 Folder"
"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 folder information
| URL | /api/<auth_token>/folders/<folder_identifier> |
| Method | GET |
| Version | 1.0 |
Description
Retrieves folder information from the OnSong library.
Path arguments
| Name | Type | Description | Required |
|---|---|---|---|
| auth_token | string | The authentication token used to authenticate the request. | Required |
| folder_identifier | string | The identifier of the folder information to be retrieved. | Required |
Response
Returns a Folder Object.
Response example
The response does not include NULL values.
{
"ID": "55E44C19-D2ED-4665-B191-C6EC9B6F60C2",
"title": "Folder Title",
"modified": "2015-04-14T11:05:21-04:00",
"orderMethod": "title",
"quantity": 1,
"created": "2015-04-14T11:05:21-04:00"
}
Delete folder
| URL | /api/<auth_token>/folders/<folder_identifier> |
| Method | DELETE |
| Version | 1.0 |
Description
Deletes a folder from your library.
Path arguments
| Name | Type | Description | Required |
|---|---|---|---|
| auth_token | string | The authentication token used to authenticate the request. | Required |
| folder_identifier | string | The identifier of the folder to be deleted. | Required |
Response
| Name | Type | Description |
|---|---|---|
| success | object | The operation was successful and basic folder 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 Folder" }
}
The following is an example of a failed operation with a 500 status code:
{
"error" : "No folder found"
}