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