Getting Started with API

Getting Started

Welcome to Lemonwhale’s API Documentation. The Lemonwhale API allows you to connect your application to Lemonwhale’s video system without having to use the web interface.

For more information about REST take a look here.

Public vs. Private API

Lemonwhale API is divided into two parts, one public and one private. The public should be used when the request is done often and in public places, for example an Play site.
The private should be used in the opposite, private places which require login or on a server, for example if you want to integrate in a CMS. The private requires an API-Key when communication with Lemonwhales server’s, while the public one doesn’t require any type of authentication.

API-Key

There are two different kind of API-Keys to use in Lemonwhales API, either an API-Key for your site or an API-Key for a specific user on your site.

Site API-Key

To access an API-Key for your site you can login on here and navigate to “Settings” -> “Site Settings” where you can generate your sites API-Key. Notice that your site only can have one API-Key at a time, so if you generate a new one the old one will no longer be valid.

You will probably need your site’s site id as well. You can find that at the same place as were you check out your API-Key.

User API-Key

User API-Key should be used in cases where you have a lot of users and doesn’t want to use the same API-Key for all the users. This API-Key will not work for all types of request that the Site API-Key will, for example list videos or liveshow on site.
If you want to start using User API-Key, please speak with your Lemonwhale contact.

Date format

This API uses ISO-8601 format for date and time representation.

In Java we can format or parse a date using a DateFormat with following serialization string: DateFormat formatter = new SimpleDateFormat(“yyyy-MM-dd’T'HH:mm:ssz”);.

In JavaScript you can use jQuery plugins like timeago or pretty date to handle this format in an elegant way.

Data formats

The API can be used either with XML or JSON. If you would like to use the api wihtin a javascript page you can also use the JSONP format.

You decide which format you want to use by providing an extension to the request name. If you would like to use xml you add .xml and if you would like to use json you add .json, similarly for jsonp you add .jsonp.

Examples are:

http://web.lemonwhale.com/web/public/video/02c26624-4c68-4b48-90f7-4d4cb6722d7f.json

http://web.lemonwhale.com/web/public/video/02c26624-4c68-4b48-90f7-4d4cb6722d7f.xml

Error messages

If some thing goes wrong, we will try to respond in the best way we can to help your to figure out why it went wrong. The error response is always constructed in the same way, and the only thing that differs is the error message itself as well as the HTTP-code.

Example of error response in XML and JSON:

<error>Could not find user JohnDoe</error>

{
    "error":"Could not find user JohnDoe"
}

Error codes from the API area listed below: