API

Introduction

The Wixi API allows you to develop your own applications using Wixi as the backend. This way, you can create software using the Wixi storage or the media reencoding and streaming system. Since the API is (kind of) based on the REST principles you can use it from any programming languages: no weird stuff, just plain old HTTP.

What can you do with the API today?

  • See and update your user profile (includes FOAF)
  • See other users profiles
  • See who your friends are (includes FOAF)
  • Search for users
  • Make new friends (accept, request) and/or fight with them (reject requests, revoke friendship)
  • Upload a new file to Wixi
  • Copy other users files to your wixi
  • Add an external link to your desktop from Youtube, DailyMotion or any of the supported 3rd party sites (or a set of links from a RSS feed)
  • Delete files
  • Rename files
  • Stream and Download files
  • List directories
  • Search for files


REST operations

The API is plain old HTTP:
  • if you want to know if your request was processed correctly or not, just take a look on the HTTP response code: 200 (or better, <300), everything is fine ; >=400 you did something wrong and >= 500 if it was our fault.
  • Do you want to download a file in your Wixi? just GET it. If you just want to see it's metadata send a HEAD request to the same URL
  • There's no weird authentication methods (HTTP Basic is the only method supported now)

Everything which is public in the Wixi Desktop Interface will be accessible via the API.
To request private data or to modify it you need to be authenticated, just send your credentials as HTTP auth.

For example, requesting your private profile is not authorized if you're not authenticated: http://v1.api.wixi.com/my_user?private=1 (will return a 401)
Instead, this will work: http://my_user:my_pass@api.wixi.com/my_user?private=1

Note: API is still not public. You can request access to api@wixi.com .

API Examples

The API should be pretty much intuitive to work with.
You can work with 4 kind of resources:
  • users
    • http://v1.api.wixi.com/my_user
  • friends
    • http://v1.api.wixi.com/my_user/friends/
    • http://v1.api.wixi.com/my_user/friends/my_friend
  • files
    • http://v1.api.wixi.com/my_user/files/
    • http://v1.api.wixi.com/my_user/files/folderli>
    • http://v1.api.wixi.com/my_user/files/folder/myfile.avi
  • messages (not ready)


Examples

It's very important to notice that the trailing slash can change the resource targeted by your request.
When the trailing slash is present, the request will be executed over THE CONTENTS of the resource. When there's no trailing slash, the request will be executed over THE RESOURCE.

All requests must include a "X-API-KEY" HTTP header with the key we assigned to your application.
Requests without this key or with an invalid key will be rejected (HTTP 403).
Alternatively you can send an "api_key" GET parameter in your request, but this is not recommended.

Some examples:

Get the profile of a user (no trailing slash!)

GET http://v1.api.wixi.com/my_user?api_key=YOUR_API_KEY_HERE

Get the private profile of a user -this includes his name, email addr, etc- (no trailing slash!)

GET http://v1.api.wixi.com/my_user?private=1

List the contents of a directory (see trailing slash)

GET http://v1.api.wixi.com/my_user/files/folder/

By default, this will return a JSON document with the following structure:

[
 {
   "status": 75,
   "name": "La Contrabanda - No Imaginas.mp3",
   "ancestors": null,
   "thumbnail": false,
   "sysId": "",
   "size": 6500375,
   "tags": "",
   "mimeType": "2",
   "hash": "093dfdbd6752e2b07a48e1c356545329",
   "depth": 1,
   "type": 0,
   "URL": "\/runa\/files\/La+Contrabanda+-+No+Imaginas.mp3",
   "sysData": null,
   "id": 4213991,
   "creationTime": "20080728180912",
   "replica": 12090,
   "ownerURL": "\/runa",
   "description": "",
   "permissions": "::",
   "owner": 32661,
   "path": "663530,4213991,",
   "children": null,
   "_jsClass": "FileSystemFile",
   "target": "093dfdbd6752e2b07a48e1c356545329.mp3",
   "parent": 663530,
   "original": false,
   "mimeSubType": "40"
 },
 {
   "status": 75, *current node status, 75 means the upload was ok and the thumbnail an streamable versions are ready*
   "name": "buda recostado.jpg", *file name*
   "ancestors": null, *if we had the parent node info preloaded you will get it here*
   "thumbnail": true, *thumbnail is ready*
   "sysId": "", *is special folder (see Wixi TV, .trashbin)*
   "size": 146356, *file size, in bytes*
   "tags": "", *tags for this file*
   "mimeType": "1", *mime type, see the table below*
   "hash": "7778fa839ee70e6b0316acb301a0c4b8", *hash that uniquely identifies this file, not always is md5!*
   "depth": 1, *number of parents to wixi fs root*
   "type": 0, *node type: 0=file, 1=folder, 2=link*
   "URL": "\/runa\/files\/buda+recostado.jpg", *resource URL, you should use this for refering to this node. this is fairly new*
   "sysData": false, *in deleted files this has the original file name*
   "id": 1125698, *internal ID*
   "creationTime": "20080213192759", *creation time: YYYYMMDDHHmmSS*
   "replica": 1125633, *if this node is a copy of another node*
   "ownerURL": "\/runa", *URL of the owner*
   "description": "", *file description*
   "permissions": "::", *file permissions*
   "owner": 32661, *owner ID*
   "path": "663530,1125698,", *path IDs, including the current node*
   "children": null, *if we had them or if you requested a recursive listing, you have the children nodes here*
   "_jsClass": "FileSystemFile", *hints to hidrate json objects back into Javascript objects*
   "target": "7778fa839ee70e6b0316acb301a0c4b8.jpg", *used internally*
   "parent": 663530, *internal ID of the parent*
   "original": true, *if this file was Uploaded by the owner (instead of just copying it from another wixi)*
   "mimeSubType": "2" *mime subtype, see table below*
 },
 {...}
]

You can do a recursive listing adding a "listing=recursive" GET parameter

Get the list of friends for a user

GET http://v1.api.wixi.com/my_user/friends/

You can also receive this list as FOAF if you:
 1. send a HTTP Accept header with: application/rdf+xml
 2. append a query string parameter: response=application/rdf+xm
  • GET http://v1.api.wixi.com/my_user/friends/?response=application/rdf%2Bxml (that's "application/rdf+xml" escaped)


Get the info for a file or directory (no trailing slash)

This might change in the future

HEAD http://v1.api.wixi.com/my_user/files/folder

(think of "ls -d folder")

Change user profile

POST http://v1.api.wixi.com/my_user

(POSTDATA is: "email=johndoe@foobar.com", use the same attributes you get from getting the private user profile)

Create a directory

PUT http://v1.api.wixi.com/my_user/files/my_dir


Upload a file

File uploading is the most complicated API function. You first need to request a upload token.
This token will be a full URL with some magic/opaque stuff. After you get this URL you need to POST your file there.

I. Request your upload token
    1. PUT http://v1.api.wixi.com/my_user/files/my_new_file_name
         Include the following parameter: "validate=1" and optional:
  • the file size (size=321239)
  • the md5 hash of the file contents (md5=de6838252f95d3b9e803b28df33b4baa)
  • overwrite=1
    2. You'll receive:
  • HTTP 200 "token" + an JSON object with a "url" property (see below for an example)
    • apikey test
    • APITest
  • HTTP 201 "created" + a FileSystemNode object (ie, the object you tried to upload was already on the system)
  • HTTP >400 "error" an error ocurred (you don't have permissions, you don't have the free space, etc)
II. If you got a 200 "token", you can upload your file     1. Make a POST request to the URL and encode the file in a POST parameter named "file"
    2. You'll receive
  • 200 code with the new FileSystemNode object
  • 403 not authorized
  • 400 other errors

Example response for a Token Request

$ curl -d validate=1 -D - -X PUT "http://runa:lalalo@api.martin.local.bsas.wixi.com/runa/files/new_file.png?api_key=123"
HTTP/1.1 200 go ahead!
Date: Wed, 23 Jul 2008 14:35:00 GMT
Server: Apache/2.2.8 (Ubuntu) PHP/5.2.4-2ubuntu5.2 with Suhosin-Patch
X-Powered-By: PHP/5.2.4-2ubuntu5.2
Content-Length: 334
Content-Type: text/plain; charset=iso-8859-1

{"url":"http:\/\/upload.martin.local.bsas.wixi.com\/?magictokenhere&API=1&cmd=upload&path=runa&name=new_file.png&target=&overwrite=&user=32661&extra=%7B%22name%22%3A%22new_file.png%22%2C%22tags%22%3A%22%22%2C%22description%22%3A%22%22%2C%22access%22%3A%22%22%2C%22uploadPath%22%3A663530%7D&signature=12e6cb9fc66d49b863028afa0f0ae22d"}

See the APIUploadTest for an example implementation of this

Output formats

Output can be serialized in a few interesting formats. All requests can be serialized in JSON and PHP (JSON is the default and recommended format).
Also, a few resources support specialized output types (RSS and FOAF).

To request a special serialization, you have 2 options:
  • Send the HTTP ACCEPT header:
    • RDF / FOAF: application/rdf+xml
    • JSON (default): text/x-json
    • RSS: application/rss+xml
  • Send a "response" parameter in the query string with the mime type or the AJAX_RESPONSE_* constants (see below). Make sure to encode the mime type!
    • http://v1.api.wixi.com/my_user/friends/?response=application/rdf+xml
    • http://v1.api.wixi.com/my_user/friends/?response=9

AJAX RESPONSE constants

AJAX_RESPONSE_XML
AJAX_RESPONSE_SERIALIZED
AJAX_RESPONSE_HTML_SERIALIZED
AJAX_RESPONSE_JSON
AJAX_RESPONSE_HTML_JSON
AJAX_RESPONSE_RDFXML
AJAX_RESPONSE_RSS
AJAX_RESPONSE_JSON_CALLBACK
2
4
5
6
7
9
10
11
XML (only work with some requests)
Output of PHP serialize()
Output of PHP serialize() wrapped in <html><body> tags
JSON
JSON wrapped in <html><body> (for use in hidden iframes)
RDF output, currently user and friend resources are encoded in FOAF
RSS output, currently search results and file listings are encoded as RSS
JSONP response is passed to a callback function on your side. Use with <script> tags and pass a "callback" GET parameter

Examples

Cross site requests

From a HTML document in your domain foobar.com call (GET) a Wixi API function:

<script type='text/javascript'>
  function listUserFriends(friends){
     ...
  }
</script>
<script type='text/javascript' src='http://v1.api.wixi.com/runa/friends/?response=11&callback=listUserFriends'></script>

Browse data as FOAF

http://v1.api.wixi.com/runa/friends/?api_key=YOUR_API_KEY_HERE&response=application/rdf%2Bxml

You can see the output in FOAF Explorer: http://xml.mfd-consult.dk/foaf/explorer/?foaf=http%3A%2F%2Fapi.wixi.com%2Fruna%2Ffriends%2F%3Fresponse%3Dapplication%2Frdf%252Bxml%26api_key%3D33

Mime Types and Subtypes

MimeTypes

Array("image"=>1,
"audio"=>2,
"video"=>3,
"application"=>4,
"text"=>5
);

Mime Subtypes

$types[1]['gif']='1';
$types[1]['jpeg']='2';
$types[1]['png']='3';
$types[1]['tiff']='4';
$types[1]['bitmap']='5';
$types[2]['mpeg']='40';
$types[2]['x-wav']='7';
$types[2]['x-ogg']='8';
$types[2]['x-realaudio']='9';
$types[2]['x-ms-wma']='10';
$types[2]['x-m4p']='11';
$types[3]['x-avi']='12';
$types[3]['x-xvid']='13';
$types[3]['x-vob']='14';
$types[3]['x-mpg2']='15';
$types[3]['x-ms-wmv']='16';
$types[3]['quicktime']='17';
$types[4]['x-shockwave-flash']='18';
$types[3]['mpeg']='6';
$types[3]['x-flv']='19';
$types[3]['x-asf']='20';
$types[3]['x-mp4']='21';
$types[3]['x-mkv']='22';
$types[3]['x-3gp']='23';
$types[3]['x-divx']='24';
$types[3]['x-gvi']='25';
$types[3]['x-ram']='26';
$types[3]['x-mod']='27';
$types[3]['x-dv']='28';
$types[3]['x-m4v']='29';
$types[5]['plain']='30';
$types[5]['html']='31';
$types[5]['xml']='32';
$types[4]['x-ms-winword']='33';
$types[4]['x-ms-excel']='34';
$types[4]['rtf']='35';
$types[4]['x-ms-powerpnt']='36';
$types[4]['x-adobe-reader']='37';
$types[4]['octet-stream']='38';
$types[5]['directory']='41';

Functionality in the near future

  • Search for files for a specific user
  • Change permissions of files
  • Report content as inappropriate
  • Get/Set goldenbook messages
Categories