Voicebox API

Voicebox provides an open REST API so that web and mobile apps can integrate with the fun functionality of Voicebox. This is the guts behind our mobile app at vbsongs.com, and how our website can display the current popular songs.

We encourage experimentation and development of features which integrate Voicebox with social networking sites and other online music systems.

Please be considerate of others, and of the fact that hundreds of paying customers use our system every day. Abuse will not be tolerated.

Packages

The Voicebox API is broken into two separate packages:

See the Voicebox Industries site for information about available packages.

API Overview

The following features are common to the entire API, regardless of which package, resource, or feature is used.

Versioning

Each URL contains a version, which is something like v1, so the actual URL would be /api/v1/songs

Current Version: v1

Formats

The URLs also contain an optional format, which can be one of: .json, .txt, or .html

If the format is unspecified, it uses the Accept header in the HTTP request. Browsers will typically use Accept: text/html, so you will get back an HTML result, which is not JSON. Though this makes for convenient testing from a browser, you should use .json in your production system.

  • json should be used by production systems
  • txt is more human-readable json
  • html is a formatted response

JSONP

The Voicebox API optionally supports JSONP responses, by supplying an additional ‘callback=myFunctionName’ parameter on any of the resources below. Note that this only works with the .json format. This will cause the response to be returned as:

myFunctionName({ ... })

Error handling in JSONP is notoriously bad. See this discussion for an overview of the problem. If there is an error, the script tag will simply not be loaded by the browser, and the AJAX call will stall. To get around this, the Voicebox API will respond with an HTTP status code of 200 even if an error occurs, and the response body will be something like:

myFunctionName({"error":"Description of the error","status":400})

The status provided is the HTTP status code that would have been received, were it not a JSONP request.

Error Handling

The HTTP responses use standard HTTP status codes.

Successful responses will be 200 OK, or 201 Created.

Error responses will contain a result like:

{"error":"Description of the error","status":400}

The status code will indicate the type of error:

400 Bad Request - there is missing or invalid data in the request
401 Unauthorized - the room_code or api_key provided is incorrect
403 Forbidden - the action is not allowed right now, e.g. the queue is limited, or requires a logged-in session
404 Not Found - the URL does not correspond to a valid resource, e.g. the song_id does not exist
500 Internal Server Error - something went wrong on our end. We’ll log it and fix it
504 Gateway Timeout - the internet is unavailable between our server and the Voicebox location

Pagination

Because there are so many songs at Voicebox (over 60000 and growing), there is no single request to get all of the song data. Instead, we provide resources to browse the song database much as one would browse a song book, by artist or by title.

Large resources, like the songs resources, return only a limited set of results, and have a page parameter to control which page is returned.

There is also a per_page parameter, which can adjust how many results come back per page, though most resources will have a maximum.

Sessions

Each API call may provide a session parameter, which should be a valid UUID, in the 8-4-4-4-12 hexadecimal format. This session is used to identify activity from a single user, for keeping track of play history, storing a user’s favorite songs, and other features as Voicebox grows. This parameter is usually optional, but some features require a session, such as getting your play history.

Clients may generate a session UUID themselves, and they do not need to actually call the Voicebox API in order to get a session. This session UUID should be stored client-side and sent with every request.

For testing, please use session 12345678-1234-1234-1234-123456abcdef

Login

In addition to sessions, the Voicebox API supports login to a customer profile, by supplying an email address. This finds an existing profile, or creates a new profile, which allows features such as play history to persist across sessions, or to be viewed from another device. Some features require a login, such as viewing a user’s favorite songs, and more to come.

Organizations

The Voicebox API supports not just the brick-and-mortar Voicebox in Portland OR, but also several other partner organizations. Each API resource accepts an additional optional parameter, called organization, which should be set to the organization key that we have provided. This is how Voicebox supports mobile apps other than its own vbsongs.com.

  • When the organization parameter is present, all results and operations via the API will be correspondingly scoped to that organization.
  • When the organization parameter is missing, it implicitly uses the Voicebox organization, and scopes accordingly.

Powered by Voicebox Industries