Requests

The API is based on HTTP, and any request is made to the site's address (i.e. http://videos.examples.com) followed by the API method name (i.e. /api/user/create or /api/tag/related).

Both GET and POST requests are allowed, but note that the GET-style query string parameters (i.e. /api/tag/related?tag=mytag) are not used on POST requests.

For example, using the related tags method a request could look like this:

https://video.example.com/api/tag/related?tag=demo

And return something like this:

<response status="ok" permission_level="anonymous" total_count="2"
cached="0">

    <relatedtag tag="screencast" url="/tag/screencast"/>
    <relatedtag tag="video" url="/tag/video"/>

</response>

 

The API expects UTF-8 formatted input and will return in UTF-8 as well.

The API is accessible via Adobe Flash and Adobe Flex. If you need to access it from a foreign domain, have a look at our cross-domain acces policies.

The next section describes how to authenticate your requests, and you should also have a look at the limits and possibilities of anonymous access to the api.

Responses

By default responses from the API come in the form of a <response> XML element (see response formats for more information). The root element will always have a status attribute detailing if the request was ok or error. Both success and failure responses are returned with the HTTP status code 200.

Success

Successful requests will return XML formatted like this (or as JSON):

<response status="ok" message="The user exists">
    <user_id>13579</user_id>
    <email>ernest@hemmingway.com</email>
    <username>ernest</username>
    <full_name>Ernest Hemmingway</full_name>
    <site_admin>1</site_admin>
    <timezone>Europe/Copenhagen</timezone>
</response>

Failure

Whenever a request to the API fails, a response detailing the exception is returned. The response includes an error_code and a detailed error description (see all error codes).

<response status="error" code="invalid_signature" message="The API signature is invalid."/>

Response formats

The API response is available in two formats: XML and JSON. By default, the API will respond in XML, but you can force the format using the format parameter:

http://videos.example.com/api/tag/list?format=xml /  http://videos.example.com/api/tag/list?format=json

Detailed above the XML responses will be wrapped in a <response> root node with a number of attributes (such as status, permission_level and cached) describing the returned data. The content of the root node varies depending on the method invoked and is described in the individual method documentation.

The JSON return format will return the same data as the XML format, but it will be formatted differently and the response will also include information about the site being queried. A request to http://videos.example.com/api/tag/list?size=2&format=json might yield:

var visual = {  "status": "ok",  "permission_level":"read",  "cached":"0",  "tags":[    {"tag": "23", "count": "4", "url": "/tag/23"},    {"tag": "3gpp", "count": "1", "url": "/tag/3gpp"}  ],  "p": "1",  "size": "2",  "total_count": "69",  "site": {    "domain": "videos.example.com",    "product_key": "tube",    "site_id": "123456",    "site_name": "Example Video Site"  },  "endpoint": "/api/tag/list"}

As you can see, the site object contains the name, id and product identifier of your site.

The variable name can be controlled by setting varname. For example, requesting http://videos.example.com/api/tag/list?format=json&varname=tags would return:

var tags = {  "status": "ok",  tags:[...]  ...}

The response is also available as a JSONP-style callback using the callback parameter. Requesting the same data with http://videos.example.com/api/tag/list?format=json&callback=updateTags gets you:

updateTags({  "status": "ok",  tags:[...]  ...})

This is valuable for cross-domain scripting in a browser:

<script>  function updateTags(o) {    for (i in o.tags) {      doEvilStuffWithTag(o.tags[i].tag);    }  }</script><script src="http://videos.example.com/api/tag/list?format=json&callback=updateTags"></script> 

Finally, you can get raw JSON data without any unnecessary syntactic sugar using raw. Asking for http://videos.example.com/api/tag/list?format=json&raw would answer:

{  "status": "ok",  tags:[...]  ...}

Pagination

A number of API methods (including for example /api/photo/list, /api/user/list and /api/tag/list) returns a list of objects. These lists will often only return a subset of the data, and the programmer will need to handle pagination explicitly. This is done using p and size:

• size: Number of items to return with each request. Where nothing else is stated, the default value for size is 20 and the maximum value is 100.
• p: The page number to return. The default value is 1 and given a size of 20, p=2 will return items 21 through 40, and p=5 will yield items 81 through 100.

Any request offering pagination will include the p and size parameters in their responses, and in addition a third property is included:

• total_count: The total number of object available through the request.

For example, you might query http://videos.example.com/api/tag/list:

<response status="ok" permission_level="anonymous" p="1" size="20" total_count="69" cached="0">  ( ... 20 tag objects ... )</response>

Based on the response, we know that there are 69 tags distributed along ceil(69/20) = 4 pages. Armed with this information we can make a few additional requests ending with http://videos.example.com/api/tag/list?size=20&p=4:

<response status="ok" permission_level="anonymous" p="4" size="20" total_count="69" cached="0">  ( ... 9 tag objects ... )</response>