Folders

Folders are used to organize sets for specific venues or other organization methods.

Find folders

URL/api/<auth_token>/folders
MethodGET
Version1.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:
  • title sorts the folders by title. Default.
  • quantity sorts the folders by the number of sets contained within.
  • orderIndex sorts the folders by a user-defined order.
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
MethodPUT
Version1.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>
MethodGET
Version1.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>
MethodDELETE
Version1.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"
}