API: Browser-based uploads
Browser-based uploading consists of two API methods:
- /api/photo/get-upload-token to predefine meta-data, specify a callback URL and retrieve an
- /api/photo/redeem-upload-token to actually upload a video or photo using the token.
This approach is designed to allow API consumers to pre-authenticate uploads to their TwentyThree sites -- and enables applications to let users upload photos and videos to TwentyThree 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.
This process also allow for mulri-file uploads via Flash, Gears, Silverlight, HTML5 and other similar endeavors. For Flash specifically, you will need to be aware of our cross-domain acces policies or host the
.swf file on your TwentyThree domain.
1. Post upload meta data to TwentyThree
Start by posting title, description, album, tags and publish status to the API alongside a
return_url where the user is returned after uploading the actual file:
http://videos.examples.com/api/photo/get-upload-token? title=My+title& album_id=12345& return_url=http://www.example.com/upload/callback?theme=green
This will return you an
upload_token plus information about the exact meta data, about the expiration of the token and about how many times the token can be used:
<response status="ok" permission_level="write" message="The upload token is ready to use" cached="0"> <upload_token>022fe6e3fb42758d6147c539727c5358af3524b1</upload_token> <title>A title for the new upload</title> <description>... and a prelimiary description</description> <publish>1</publish> <tags>product:1234, testemonial</tags> <user_id>17488</user_id> <album_id></album_id> <max_uploads>1</max_uploads> <valid_minutes>180</valid_minutes> <valid_until>1266711372</valid_until> <return_url>http://www.example.com/upload/callback?theme=green</return_url> </response>
In this example, you're getting a token valid for one upload and for 3 hours.
2. Get the
From this returned information you will need to extract the
upload_token. In this case, the token is:
3. Build the HTML form using the
Using this token you can now build a simple HTML form for the user.
<form action="http://videos.example.com/api/photo/redeem-upload-token" method="post" enctype="multipart/form-data"> <input type="hidden" name="upload_token" value="022fe6e3fb42758d6147c539727c5358af3524b1" /> <input type="file" name="file" /> <input type="submit" value="Upload video" /> </form>
4a. Handle the call-back after the upload completes.
The callback URL is defined by the
return_url parameter, and the callback request will always take the form of a HTTP 301 redirect to a GET-style address.
The request will always include the upload_token and domain as a parameter. If the upload succeeded, the parameters photo_id, token, tree_id will be included:
http://www.example.com/upload/callback? theme=green& domain=videos.example.com& upload_token=022fe6e3fb42758d6147c539727c5358af3524b1& photo_id=12345& tree_id=97531& token=mhpDudicFtdjz1isvidhnzsgqv3kaske
4b. Handle the call-back on upload errors
On upload failure, the user is sent to the same callback page. The request includes an error_message parameter alongside upload_token and domain. For example:
http://www.example.com/upload/callback? theme=green& domain=videos.example.com& upload_token=022fe6e3fb42758d6147c539727c5358af3524b1& error_message=The+file+type+isn't+supported
Uploading through Flash
You can use a method very similar to the method prescribed above for uploading via Adobe Flash (or equivalent technologies). In these cases, you might not be able to control or even make client-side redirects -- for example, Flash won't redirect to
return_url after the upload.
To overcome this, set
background_return_p=1 when creating the token. This will cause the callback request to be made from the server-side. You can read more about set-up and returns in the relevant documentation.