Books

Books are used to organize large libraries of songs into collections.

List books

URL/api/<auth_token>/books
MethodGET
Version1.0

Description

Lists books 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>/books?q=sample&sort=title

Name Type Description Required
q string The query to look up books by title Optional
sort string The sort method to use when returning sets. Options include:
  • title sorts books by title. Default.
  • orderIndex sorts books by their set position.
  • quantity sorts books 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

{
  "count" : 1,
  "results" : [
    {
      "ID" : "Sample Book",
      "name" : "Sample Book"
    }
  ],
  "attributes" : {
    "q" : "sample",
    "sort" : "title"
  }
}

Create book

URL/api/<auth_token>/books
MethodPUT
Version1.0

Description

Creates a new book 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
name string The name of the book to create. Required
songs array An array of song identifiers to add to the book. 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 creation:

{
  "success" : {
    "ID" : "Christmas Carols", 
    "name" : "Christmas Carols"
  }
}

The following is an example of a failed operation with a 500 status code:

{
  "error" : "Name is required"
}

View book information

URL/api/<auth_token>/books/<book_identifier>
MethodGET
Version1.0

Description

Retrieves book information from the OnSong library.

Path arguments

Name Type Description Required
auth_token string The authentication token used to authenticate the request. Required
book_identifier string The name of the book to be retrieved. This can be the name of the book to be retrieved or the term "current" to use the currently active book. Required

Query arguments

Name Type Description Required
show_songs boolean Determines if songs should be displayed using the "songs" property. Optional

Response

Name Type Description
ID string The unique identifier of the book.
name string The name of the book.
songs array The list of songs that are in the set sorted in custom order.

Response example

The response does not include NULL values.

{
  "ID" : "Sample",
  "name" : "Sample",
  "songs" : [
    {
      "ID" : "ADC7622D-EF15-4EA0-9DC0-A8E086F8D8A3",
      "title" : "Oceans (Where Feet May Fail)",
      "favorite" : 0,
      "usefile" : false,
      "key" : "D",
      "artist" : "Hillsong United"
    }
  ]
}

Update book

URL/api/<auth_token>/books/<set_identifier>
MethodPOST
Version1.0

Description

Updates a book 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
name string The name of the set. Optional
songs array An array of song identifiers in the preferred order. 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" : { "/books/837BB846-F374-4369-86ED-2A1A08EE131B/name" : "Party Songs" }
  },
  {
    "success" : { "/books/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 book

URL/api/<auth_token>/books/<book_identifier>
MethodDELETE
Version1.0

Description

Deletes a book from your library.

Path arguments

Name Type Description Required
auth_token string The authentication token used to authenticate the request. 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", "name" : "Deleted Book" }
}

The following is an example of a failed operation with a 500 status code:

{
  "error" : "No book found"
}