Lyrical Systems API =================== Lyrical Systems provides an open REST API so that web and mobile apps can integrate with the fun functionality of its karaoke systems. This is the guts behind the mobile apps that we support for companies like Voicebox at [vbsongs.com](https://vbsongs.com), and how websites can display the current popular songs. We encourage experimentation and development of features which integrate 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 Lyrical Systems API is broken into separate packages: - [Karaoke Cloud](documentation/cloud.html) - [GRM (Guest Relationship Management)](documentation/grm.html) - [Integrated GRM and POS Reporting](documentation/reports.html) See the [Lyrical Systems](https://lyricalsystems.com/packages/) site for information about available packages. Please [contact us](https://lyricalsystems.com/contact/) if you have further interest in using this API. --- API Overview ------------ The following features are common to the entire API, regardless of which package, resource, or feature is used. - [Versioning](#versioning) - [Result Formats](#result-formats) - [JSONP](#jsonp) - [Error Handling](#error-handling) - [Pagination](#pagination) - [Sessions](#sessions) - [Login](#login) - [Organizations](#organizations) - [Ping](#ping) --- Versioning ------------------------------------ Each URL contains a *version*, which is something like v1, so the actual URL would be /api/v1/songs ##### Current Version: v1 --- Result 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 Lyrical Systems API optionally supports [JSONP](http://bob.pythonmac.org/archives/2005/12/05/remote-json-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](http://stackoverflow.com/questions/5334413/parsing-jsonp-response-in-javascript-when-4xx-or-5xx-http-error-code-is-present) 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 Lyrical 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 brick-and-mortar location --- Pagination ------------------------------------ Because there are so many songs available (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](http://en.wikipedia.org/wiki/Universally_unique_identifier), 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 we grow. 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 Lyrical 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 Lyrical API supports login to a user 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 Lyrical API supports many brick-and-mortar locations. It was originally developed to support [Voicebox Karaoke](https://voiceboxkaraoke.com) in Portland OR, but it also supports several other partner organizations across the country such as [Punchbowl Social](https://www.punchbowlsocial.com). Each API resource accepts an additional parameter, called **organization**, which should be set to the *organization key* that we have provided. This is how Lyrical supports each independent mobile app such as [vbsongs.com](https://vbsongs.com) for Voicebox, and [pbs-karaoke.com](https://pbs-karaoke.com) for Punchbowl Social. * For testing, please use organization `00000000000000000000000000000000` and room_code `CQFW` * If you were previously able to use the API to implicitly access Voicebox, note that the `organization` parameter is now required --- GET /api/*version*/ping.*format* ---------------------------------------------------- Returns a result from the API, to ensure connectivity. ### Parameters None ### Examples To ping the API GET /api/v1/ping Or via curl curl https://app.lyricalsystems.com/api/v1/ping ### Example Response { "ok": true, "now": "2016-10-25T09:55:20.190Z" } --- ## *Powered by [Lyrical Systems](https://lyricalsystems.com/)*