Permalink
Browse files

Uncommitted updates from steffentchr

  • Loading branch information...
1 parent a510173 commit c177981fab7027e74b3a048c95a617c140bd539f nick committed May 26, 2011
Showing with 120 additions and 36 deletions.
  1. +1 −1 analytics-report-event.md
  2. +2 −1 analytics-report-play.md
  3. +1 −1 distribution-ios-unregister-device.md
  4. +55 −13 index.md
  5. +12 −2 photo-list.md
  6. +9 −1 photo-replace.md
  7. +40 −17 photo-section-list.md
View
2 analytics-report-event.md
@@ -1,4 +1,4 @@
-# API Method: /api/analtics/report/play
+# API Method: /api/analytics/report/play
# flags=comments
Report an event back to the analytics engine.
View
3 analytics-report-play.md
@@ -1,4 +1,4 @@
-# API Method: /api/analtics/report/play
+# API Method: /api/analytics/report/play
# flags=comments
Report a playback event back to the analytics engine.
@@ -15,6 +15,7 @@ The reporting methods are used to report additional contextual information about
<tr><td><tt>photo_id</tt> <small>(required)</small></td><td>The ID of the playing video.</td></tr>
<tr><td><tt>time_start</tt> <small>(required)</small></td><td>The start time in seconds of the current playback.</td></tr>
<tr><td><tt>time_end</tt></td><td>The end time in seconds of the current playback.</td></tr>
+ <tr><td><tt>time_total</tt></td><td>The total time in seconds of the video currently paying.</td></tr>
<tr><td><tt>user_player_type</tt></td><td>The type of player used by the client (should be <tt>flash</tt> or <tt>html5</tt>).</td></tr>
<tr><td><tt>user_player_version</tt></td><td>The version of player used by the client.</td></tr>
<tr><td><tt>user_player_resolution</tt></td><td>The resolution of the client's screen.</td></tr>
View
2 distribution-ios-unregister-device.md
@@ -1,4 +1,4 @@
-# API Method: /api/distribution/ios/register-device
+# API Method: /api/distribution/ios/unregister-device
# flags=comments
Unregister an already [registered](distribution-iso-register-device) iOS subscription for push notications.
View
68 index.md
@@ -7,6 +7,34 @@ This API is designed to be used in an array of different contexts: Browser- and
---
+## How are you planning to use the API?
+
+The documention details a number of different tools available for programmers. Depending on how you will be integrating against the API you likely will not be using all of the available bits and pieces &minus; and for that reason it's important to ask *how* you will be using the API. In many cases, you won't need to worry about OAuth and access tokens.
+
+A few examples:
+
+**_Setting up a designed videosite with my own branding, my own content, on my own domain_**:<br/>
+This is the core promise of 23 Video, so you won't even need to use the API to achieve this goal. Consult [the design guide](/design/) for information on how to get started.
+
+**_Re-using data from a public site to display thumbnails or embed videos_**:<br/>
+In this case, you can skip OAuth entirely, an simply extract [JSON](http://reinvent.23video.com/api/photo/list?format=json) or [XML](http://reinvent.23video.com/api/photo/list?format=xml) lists of content. Be sure to to understand [response formats](#response-formats), [pagination](#pagination) and the limitation of [anonymous acess](#anonymous-access) -- and then simply refer to [the method documentation](#methods).
+
+**_Using the 23 site as a private archive for video_**:<br/>
+Here, you will need OAuth signatures in order to sign requests to the API. You need to be confortable with [the flow of OAuth](oauth), find a [good OAuth library](http://oauth.net/code/) in your language of choice, and know the [the API methods](#methods). You should create a set of [_privileged credentials_](#permission-levels) from the backend of your site under _Settings_ &rarr; _API & Application_ to access the API.
+
+**_Allowing user uploads to the 23 site_**:<br/>
+Again, you need OAuth signatures (see above), but you can use [_privileged credentials_](#permission-levels) from _Settings_ &rarr; _API & Application_ in the site's backend. You have a choice between [server-based](photo-upload) or [browser-based](browser-based-uploads) uploads, and you should understand [the concept of pingbacks](#pingbacks).
+
+**_Having the user log in to their 23 site site to grant you access_**:<br/>
+This is the only case where you will need to worry about [the OAuth authentication flow](oauth) (since you can use [_privileged credentials_](#permission-levels) otherwise). Along with everything else, you need to decide on a [permission level](#permission-levels) to authenticate users at.
+
+**_Giving visitors access to content through SSO or a paywall_**:<br/>
+There are two different ways of granting user access: [Time-limited tokens](#time-limited-tokens) grants access to a single video for a limited time. And [Session signing](session-get-token) will grant them access to the content on an entire site. The token approach is designed for securely sharing a piece of content while the session aproach is designed to grant users full access to a site, it's content and the features afforded by the 23 Video templating engine.
+
+As is clear from this list, the 23 API can be used to achieve vastly different goals in different contexts. If you unsure on how to approach an integration, [just ask us](developers@23company.com).
+
+---
+
## 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 <a href="http://visualblog.net">Visualblog</a>), with photos (on <a href="http://visualblog.net">Visualblog</a>), and with videos (on <a href="http://www.23video.com">23 Video</a> and <a href="http://visualblog.net">Visualblog</a>).
@@ -74,11 +102,11 @@ We encourage you to use the generic domain, since this will handle domain change
<br/>
-<b>You can find more information on how to use OAuth 1.0a with the 23 API in the [OAuth set-up and flow](oauth) document.</b>
+<b>You can find more information on how to use OAuth 1.0a with the 23 API in the [OAuth set-up and flow](oauth) document. Please refer to this document if you at all unsure about how to use OAuth with this API.</b>
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](http://oauth.net/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](http://github.com/23/DeveloperDocumentation/tree/master/lib/php/)
+We've also created a set of samples on how to authenticate your application and communicate with the 23 API in [PHP](http://github.com/23/DeveloperDocumentation/tree/master/lib/php/) and [Ruby](http://github.com/23/DeveloperDocumentation/tree/master/lib/ruby/).
---
@@ -130,7 +158,23 @@ Methods for creating and managing albums and channels.
Methods for listing and managing comments.
-* [/api/comment/list](comment-list): List comments
+* [/api/comment/add](comment-add): Add a comment
+* [/api/comment/delete](comment-delete): Delete an existing comment
+* [/api/comment/list](comment-list): List or search for comments
+
+### Distributions
+
+Methods for managing distribution points
+
+* [/api/distribution/ios/push-notification](distribution-ios-push-notification): Send push notifications to all registered iOS devices.
+* [/api/distribution/ios/register-device](distribution-ios-register-device): Register an iOS device such as an iPhone, iPad or iPod Touch for push notications.
+* [/api/distribution/ios/unregister-device](distribution-ios-unregister-device): Unregister an already registered iOS subscription for push notications.
+
+### Licenses
+
+Methods for listing and managing licenses.
+
+* [/api/license/list](license-list): List licenses.
### Photos and videos
@@ -144,6 +188,13 @@ Methods for uploading and managing videos and photos.
* [/api/photo/update](photo-update): Update the meta data of a photo or video
* [/api/photo/upload](photo-upload): Upload a new photo or video.
+### Players
+
+Methods for listing and use video players.
+
+* [/api/player/list](player-list): List available video players
+* [/api/player/settings](player-setting): Request specific player settings
+
### Sections
Methods for managing and listing sections or chapters within video clips.
@@ -195,15 +246,6 @@ Methods for managing users.
* [/api/user/list](user-list): List users
* [/api/user/redeem-login-token](user-redeem-login-token): Log in a user using a [login token](user-get-login-token).
-<div style="display:none;">
-### Video player
-
-Methods for listing and embedding video players
-
-* [/api/player/list](player-list): List available video players.
-* [/api/player/embed](player-embed): Get a video embed code for a specific player.
-</div>
-
---
@@ -469,7 +511,7 @@ Only [`photo`](#terminology) objects are subject to pingback notifications.
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](browser-based-uploads).
+** The entire flow is detailed and exemplified in [Using browser-based with 23 Video](browser-based-uploads).**
---
View
14 photo-list.md
@@ -62,10 +62,11 @@ Note, that since the `photo_id` and `album_id` parameters might both be matched
<tr>
<td>
- <tt>tag</tt>
+ <tt>tags</tt>
</td>
<td>
- Search for one or more tags. To search for multiple tags, just include multiple <tt>?tag=...</tt> parameters.
+ Search for one or more tags.
+ To search for multiple tags, separate tags with spaces. Multi-word tags can be quotes with <tt>"</t>.
</td>
</tr>
@@ -193,6 +194,15 @@ Note, that since the `photo_id` and `album_id` parameters might both be matched
<tr>
<td>
+ <tt>license_id</tt>
+ </td>
+ <td>
+ The license associated with the content item. See [/api/license/list](license-list) for information on available values.
+ </td>
+ </tr>
+
+ <tr>
+ <td>
<tt>p</tt>
</td>
<td>
View
10 photo-replace.md
@@ -10,8 +10,16 @@ Please note, that you won't be able to replace an actual video on [23 Video](htt
<table class="pretty">
<tr><th>Parameter</th><th>Description</th></tr>
- <tr><td><tt>file</tt> <small>(required)</small></td><td>The photo file to upload.</td></tr>
<tr><td><tt>photo_id</tt> <small>(required)</small></td><td>The photo or video to replace.</td></tr>
+ <tr><td><tt>file</tt></small></td><td>The photo file to replace a photo with, or to use as a thumbnail for a video.</td></tr>
+ <tr>
+ <td>
+ <tt>time</tt>
+ </td>
+ <td>
+ When replacing the thumbnail of a video, you can extract the thumb from a specific part of the video (i.e. <tt>40.2</tt>). Also, have a look at <a href="photo-frame">/api/photo/frame</a>.
+ </td>
+ </tr>
</table>
View
57 photo-section-list.md
@@ -40,34 +40,57 @@ For non-public sites, the minimum level is:
### Example XML Response
-
<response status="ok" permission_level="anonymous"
- total_count="3" cached="1" cache_time="1291469279">
- <section section_id="101674" start_time="0" title="Earth"
- description="" link="/video/101353/101674/earth" />
- <section section_id="102000" start_time="180" title="Wind"
- description="" link="/video/101353/102000/wind" />
- <section section_id="101661" start_time="381" title="... and Fire"
- description="" link="/video/101353/101661/and-fire" />
+ total_count="6" cached="1" cache_time="1296413456">
+ <section section_id="7890" start_time="0"
+ title="It was the best of times"
+ link="/video/12345/7890/it-was-the-best-of-times"
+ thumbnail_photo_id="12345" thumbnail_tree_id="7340"
+ thumbnail_token="71a669eee625655a86cebcbad92e043"
+ quad100_download="/7340/12345/71a669eee625655a86cebcbad92e043/quad100"
+ quad50_download="/7340/12345/71a669eee625655a86cebcbad92e043/quad50"
+ standard_download="/7340/12345/71a669eee625655a86cebcbad92e043/standard"
+ portrait_download="/7340/12345/71a669eee625655a86cebcbad92e043/portrait"
+ medium_download="/7340/12345/71a669eee625655a86cebcbad92e043/medium"
+ small_download="/7340/12345/71a669eee625655a86cebcbad92e043/small"
+ quad16_download="/7340/12345/71a669eee625655a86cebcbad92e043/quad16"
+ large_download="/7340/12345/71a669eee625655a86cebcbad92e043/large"
+ quad75_download="/7340/12345/71a669eee625655a86cebcbad92e043/quad75">
+ <description>A multi-
+ line
+ description</description>
+ </section>
+ ...
</response>
+
### Example JSON Response
{
"status": "ok",
"permission_level":"anonymous",
"cached":"1",
- "cache_time":"1291469615",
+ "cache_time":"1296413646",
"sections":[
- {"section_id": "101674", "start_time": "0", "title": "Earth",
- "description": "", "link": "/video/101353/101674/earth"},
- {"section_id": "102000", "start_time": "180", "title": "Wind",
- "description": "", "link": "/video/101353/102000/wind"},
- {"section_id": "101661", "start_time": "381", "title": "... and Fire",
- "description": "", "link": "/video/101353/101661/and-fire"}],
+ {"section_id": "12345", "start_time": "0",
+ "title": "It was the best of times",
+ "link": "/video/12345/12345/it-was-the-best-of-times",
+ "thumbnail_photo_id": "12345", "thumbnail_tree_id": "7340",
+ "thumbnail_token": "71a669eee625655a86cebcbad92e043",
+ "quad100_download": "/7340/12345/71a669eee625655a86cebcbad92e043/quad100",
+ "quad50_download": "/7340/12345/71a669eee625655a86cebcbad92e043/quad50",
+ "standard_download": "/7340/12345/71a669eee625655a86cebcbad92e043/standard",
+ "portrait_download": "/7340/12345/71a669eee625655a86cebcbad92e043/portrait",
+ "medium_download": "/7340/12345/71a669eee625655a86cebcbad92e043/medium",
+ "small_download": "/7340/12345/71a669eee625655a86cebcbad92e043/small",
+ "quad16_download": "/7340/12345/71a669eee625655a86cebcbad92e043/quad16",
+ "large_download": "/7340/12345/71a669eee625655a86cebcbad92e043/large",
+ "quad75_download": "/7340/12345/71a669eee625655a86cebcbad92e043/quad75",
+ "description": "A multi-\nline \ndescription"
+ }, ...],
"p": "1",
"size": "1",
- "total_count": "3",
- "site": { ... },
+ "total_count": "6",
+ "site": {...},
"endpoint": "/api/photo/section/list"
}

0 comments on commit c177981

Please sign in to comment.