Sets

Sets are used to pull songs and place in a specific order for playing events.

Find sets

URL/api/<auth_token>/sets
MethodGET
Version1.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:
  • title sorts the sets by set title. Default.
  • date sorts the sets by the date of the set.
  • added sorts the sets by date the set was created.
  • quantity sorts the sets by the number of songs contained within.
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
MethodPUT
Version1.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>
MethodGET
Version1.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)
MethodGET
Version1.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:
  • default when no format is specified, the content is returned as an OnSong archive.
  • onsong returns the set in the OnSong file format.
  • chordpro returns the set formatted using the ChordPro syntax.
  • txt returns the set as plain text.
  • html returns the set in an HTML format.
  • pdf returns the set as a formatted PDF file.
  • opensong returns the set in the OpenSong XML file format.
  • usr returns the set in the SongSelect USR file format.
  • archive returns the set in the OnSong archive format.
Optional

Response

Returns the content of the set.

Update set

URL/api/<auth_token>/sets/<set_identifier>
MethodPOST
Version1.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>
MethodDELETE
Version1.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"
}