The API



The 23 API

This document describes the REST API for Visualplatform, 23 Video and Visualblog. Please note that access to the API depends on your product and subscription -- and that it may not be available to you. Contact us if you have questions in this regard.

This API is designed to be used in an array of different contexts: Browser- and JavaScript-based mashups with 23's products; customized video players in Adobe Flash or Adobe Flex; selecting and embedding content into a content management system; single sign-on or paywall-based access to 23 Video; or full-fledged video or community sites using 23 Video as their backend.

Terminology

For legacy reasons all 23 APIs reference the object type photo. However, depending on the service the API is used with, the photo object type is interchangeable with text posts (on Visualblog), with photos (on Visualblog), and with videos (on 23 Video and Visualblog).

The API or The 23 API in this document refers to a set of methods made available on the 23 platform in a well-defined manner and enabling programmers to retrieve data from and write data back to the system. The Client in the documentation can refer either to a browser, to the person using the browser, or generally to the program accessing the API.

The examples below refer to http://videos.examples.com. In the real world, the domain should be replaced with the domain for the site you're querying.

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:

http://videos.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.

Authentication

The 23 API uses the OAuth 1.0a protocol for user authorization and application identification.

Generally, some requests can be made anonymously, but whenever your application needs to read unpublished data or update or add new data, authentication is required. This is done by setting up consumer key and a consumer secret for you application, and then by having an existing user authorize your access. When this is done, you'll have an additional access token and am access token secret which will be used alongside your consumer credentials to sign all requests.

All interaction with the OAuth authentication process in done through a generic domain, http://api.visualplatform.net/oauth/*, or through your site's own domain, http://videos.example.com/oauth/*.

We encourage you to use the generic domain, since this will handle domain changes gracefully and will allow you to reuse code. Requests to http://api.visualplatform.net/oauth/access_token will return the domain to use for all subsequent requests to the API (more).

Request Token URL   http://api.visualplatform.net/oauth/request_token
Access Token URL   http://api.visualplatform.net/oauth/access_token
Authorize URL   http://api.visualplatform.net/oauth/authorize
Signing mechanism   HMAC-SHA1

You can find more information on how to use OAuth 1.0a with the 23 API in the OAuth set-up and flow document.

At first glance, the OAuth process might seem intimidating, but it has a major upside: It's used by Google, Yahoo, Twitter and tons of other services, which means that most web-programming languages already has one or more implementations to handle all necessary communication including both the authentication process and all request to the 23 API. You can check out which libraries are available to you at the OAuth Code page.

We've also created a set of samples on how to authenticate your application and communicate with the 23 API in PHP samples

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."/>

Methods

Albums or channels

Methods for creating and managing albums and channels.

Comments

Methods for listing and managing comments.

Photos and videos

Methods for uploading and managing videos and photos.

Sessions

Methods controlling access to a closed site and for implementing single sign-on.

Site

Methods for querying meta data about sites.

Tags

Methods for searching tags.

Testing

Methods for testing communication with the API

Users

Methods for managing users.

### Video player Methods for listing and embedding video players

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

As 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:

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

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>

Anonymous access

A number of the API methods allow anonymous access to the public data from public sites. For example, a request to http://videos.example.com/api/photo/list will yield a list of published videos of the site including information on how to play and embed these videos.

Of course, unpublished content on public sites and any content on non-public sites will not be available to anonymous API calls. For more information about access and permission levels, refer to the next section.

Permission levels

The API operates with a set of different permission levels. At each level, some actions are allowed and some are prohibited:

The levels are listed in ascending order, meaning that super authentication will give access to all lesser levels as well, and a client with read will also have anonymous and none rights.

How these rules are applied to methods is detailed under the individual method documentation. Whenever a request is denied due to lack of permissions, an error message is return detailing both the client's actual level and the level necessary:

<response status="error" permission_level="none" code="permission_denied" 
  message="You don't have the necessary permissions to 
  perform this action (required level: 'admin')"/>
  ...
</response>

Or in JSON speak:

{
  "status": "error", 
  "message":"You don't have the necessary permissions to 
    perform this action (required level: 'admin')",
  "code":"permission_denied",
  "permission_level":"none",
  "endpoint": "/api/user/create"
}

Any request to the API will also list the client's permission level in the response attributes. For example:

<response status="ok" permission_level="read" p="1" size="20" total_count="16" cached="0">

Caching

Anonymous requests to the API are subject to caching. This means that responses can be cached for a period of up to 30 minutes. Signed requests to the API are never cached.

Cached responses will have cached=1 set in the response. For example in XML responses:

<response status="ok" p="1" size="20" total_count="1" cached="1" cache_time="1266304557">
  ...
</response>

Or in the JSON response:

{
  "status": "ok", 
  "cached":"1",
  "cache_time":"1266304557",
  ....
}

The extra property cache_time notes when the content of the response was originally cached in seconds since epoch. For example, these responses were originally cached on February 16th 2010 at 08:15am.

For performance reasons, we ask you to use the cached version of any request, but you will be able to ask for a non-cached version of a response either by signing your requests or by adding a ?time=<current_timestamp> parameter to your request.

Browser-based uploads

Browser-based uploading is designed to allow API consumers to pre-authenticate uploads to their 23 sites -- and enables applications to let users upload photos and videos to 23 using browser-based uploading. This scheme allows you to accept uploads from users without ever having to proxy or host the files from you server. You should opt for this approach to uploading if you do not want to host or store the uploaded files.

The entire flow is described here

Sample implementations and testing

You can test and debug access to The 23 API using our sample scripts. These scripts also serve an exmaple on how you might interact with the API.

Any questions?

As noted in the beginning of this document, the 23 API is designed to be used in a multitude of different contexts. If you find it comes up short and have suggestions for improvements -- or if you have questions on how to use the API -- feel free to post a message in out Developer Community or send an e-mail directly to steffen@23company.com

Add a comment...

Name
E-mail
Web
 
Connect with Faceboook
Content