Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Uncommitted updates from steffentchr

  • Loading branch information...
commit c177981fab7027e74b3a048c95a617c140bd539f 1 parent a510173
nick authored
2  analytics-report-event.md
Source Rendered
... ... @@ -1,4 +1,4 @@
1   -# API Method: /api/analtics/report/play
  1 +# API Method: /api/analytics/report/play
2 2 # flags=comments
3 3
4 4 Report an event back to the analytics engine.
3  analytics-report-play.md
Source Rendered
... ... @@ -1,4 +1,4 @@
1   -# API Method: /api/analtics/report/play
  1 +# API Method: /api/analytics/report/play
2 2 # flags=comments
3 3
4 4 Report a playback event back to the analytics engine.
@@ -15,6 +15,7 @@ The reporting methods are used to report additional contextual information about
15 15 <tr><td><tt>photo_id</tt> <small>(required)</small></td><td>The ID of the playing video.</td></tr>
16 16 <tr><td><tt>time_start</tt> <small>(required)</small></td><td>The start time in seconds of the current playback.</td></tr>
17 17 <tr><td><tt>time_end</tt></td><td>The end time in seconds of the current playback.</td></tr>
  18 + <tr><td><tt>time_total</tt></td><td>The total time in seconds of the video currently paying.</td></tr>
18 19 <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>
19 20 <tr><td><tt>user_player_version</tt></td><td>The version of player used by the client.</td></tr>
20 21 <tr><td><tt>user_player_resolution</tt></td><td>The resolution of the client's screen.</td></tr>
2  distribution-ios-unregister-device.md
Source Rendered
... ... @@ -1,4 +1,4 @@
1   -# API Method: /api/distribution/ios/register-device
  1 +# API Method: /api/distribution/ios/unregister-device
2 2 # flags=comments
3 3
4 4 Unregister an already [registered](distribution-iso-register-device) iOS subscription for push notications.
68 index.md
Source Rendered
@@ -7,6 +7,34 @@ This API is designed to be used in an array of different contexts: Browser- and
7 7
8 8 ---
9 9
  10 +## How are you planning to use the API?
  11 +
  12 +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.
  13 +
  14 +A few examples:
  15 +
  16 +**_Setting up a designed videosite with my own branding, my own content, on my own domain_**:<br/>
  17 +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.
  18 +
  19 +**_Re-using data from a public site to display thumbnails or embed videos_**:<br/>
  20 +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).
  21 +
  22 +**_Using the 23 site as a private archive for video_**:<br/>
  23 +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.
  24 +
  25 +**_Allowing user uploads to the 23 site_**:<br/>
  26 +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).
  27 +
  28 +**_Having the user log in to their 23 site site to grant you access_**:<br/>
  29 +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.
  30 +
  31 +**_Giving visitors access to content through SSO or a paywall_**:<br/>
  32 +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.
  33 +
  34 +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).
  35 +
  36 +---
  37 +
10 38 ## Terminology
11 39
12 40 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
74 102
75 103 <br/>
76 104
77   -<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>
  105 +<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>
78 106
79 107 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.
80 108
81   -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/)
  109 +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/).
82 110
83 111 ---
84 112
@@ -130,7 +158,23 @@ Methods for creating and managing albums and channels.
130 158
131 159 Methods for listing and managing comments.
132 160
133   -* [/api/comment/list](comment-list): List comments
  161 +* [/api/comment/add](comment-add): Add a comment
  162 +* [/api/comment/delete](comment-delete): Delete an existing comment
  163 +* [/api/comment/list](comment-list): List or search for comments
  164 +
  165 +### Distributions
  166 +
  167 +Methods for managing distribution points
  168 +
  169 +* [/api/distribution/ios/push-notification](distribution-ios-push-notification): Send push notifications to all registered iOS devices.
  170 +* [/api/distribution/ios/register-device](distribution-ios-register-device): Register an iOS device such as an iPhone, iPad or iPod Touch for push notications.
  171 +* [/api/distribution/ios/unregister-device](distribution-ios-unregister-device): Unregister an already registered iOS subscription for push notications.
  172 +
  173 +### Licenses
  174 +
  175 +Methods for listing and managing licenses.
  176 +
  177 +* [/api/license/list](license-list): List licenses.
134 178
135 179 ### Photos and videos
136 180
@@ -144,6 +188,13 @@ Methods for uploading and managing videos and photos.
144 188 * [/api/photo/update](photo-update): Update the meta data of a photo or video
145 189 * [/api/photo/upload](photo-upload): Upload a new photo or video.
146 190
  191 +### Players
  192 +
  193 +Methods for listing and use video players.
  194 +
  195 +* [/api/player/list](player-list): List available video players
  196 +* [/api/player/settings](player-setting): Request specific player settings
  197 +
147 198 ### Sections
148 199
149 200 Methods for managing and listing sections or chapters within video clips.
@@ -195,15 +246,6 @@ Methods for managing users.
195 246 * [/api/user/list](user-list): List users
196 247 * [/api/user/redeem-login-token](user-redeem-login-token): Log in a user using a [login token](user-get-login-token).
197 248
198   -<div style="display:none;">
199   -### Video player
200   -
201   -Methods for listing and embedding video players
202   -
203   -* [/api/player/list](player-list): List available video players.
204   -* [/api/player/embed](player-embed): Get a video embed code for a specific player.
205   -</div>
206   -
207 249
208 250
209 251 ---
@@ -469,7 +511,7 @@ Only [`photo`](#terminology) objects are subject to pingback notifications.
469 511
470 512 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.
471 513
472   -The entire flow is described [here](browser-based-uploads).
  514 +** The entire flow is detailed and exemplified in [Using browser-based with 23 Video](browser-based-uploads).**
473 515
474 516 ---
475 517
14 photo-list.md
Source Rendered
@@ -62,10 +62,11 @@ Note, that since the `photo_id` and `album_id` parameters might both be matched
62 62
63 63 <tr>
64 64 <td>
65   - <tt>tag</tt>
  65 + <tt>tags</tt>
66 66 </td>
67 67 <td>
68   - Search for one or more tags. To search for multiple tags, just include multiple <tt>?tag=...</tt> parameters.
  68 + Search for one or more tags.
  69 + To search for multiple tags, separate tags with spaces. Multi-word tags can be quotes with <tt>"</t>.
69 70 </td>
70 71 </tr>
71 72
@@ -193,6 +194,15 @@ Note, that since the `photo_id` and `album_id` parameters might both be matched
193 194
194 195 <tr>
195 196 <td>
  197 + <tt>license_id</tt>
  198 + </td>
  199 + <td>
  200 + The license associated with the content item. See [/api/license/list](license-list) for information on available values.
  201 + </td>
  202 + </tr>
  203 +
  204 + <tr>
  205 + <td>
196 206 <tt>p</tt>
197 207 </td>
198 208 <td>
10 photo-replace.md
Source Rendered
@@ -10,8 +10,16 @@ Please note, that you won't be able to replace an actual video on [23 Video](htt
10 10
11 11 <table class="pretty">
12 12 <tr><th>Parameter</th><th>Description</th></tr>
13   - <tr><td><tt>file</tt> <small>(required)</small></td><td>The photo file to upload.</td></tr>
14 13 <tr><td><tt>photo_id</tt> <small>(required)</small></td><td>The photo or video to replace.</td></tr>
  14 + <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>
  15 + <tr>
  16 + <td>
  17 + <tt>time</tt>
  18 + </td>
  19 + <td>
  20 + 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>.
  21 + </td>
  22 + </tr>
15 23 </table>
16 24
17 25
57 photo-section-list.md
Source Rendered
@@ -40,16 +40,29 @@ For non-public sites, the minimum level is:
40 40
41 41 ### Example XML Response
42 42
43   -
44 43 <response status="ok" permission_level="anonymous"
45   - total_count="3" cached="1" cache_time="1291469279">
46   - <section section_id="101674" start_time="0" title="Earth"
47   - description="" link="/video/101353/101674/earth" />
48   - <section section_id="102000" start_time="180" title="Wind"
49   - description="" link="/video/101353/102000/wind" />
50   - <section section_id="101661" start_time="381" title="... and Fire"
51   - description="" link="/video/101353/101661/and-fire" />
  44 + total_count="6" cached="1" cache_time="1296413456">
  45 + <section section_id="7890" start_time="0"
  46 + title="It was the best of times"
  47 + link="/video/12345/7890/it-was-the-best-of-times"
  48 + thumbnail_photo_id="12345" thumbnail_tree_id="7340"
  49 + thumbnail_token="71a669eee625655a86cebcbad92e043"
  50 + quad100_download="/7340/12345/71a669eee625655a86cebcbad92e043/quad100"
  51 + quad50_download="/7340/12345/71a669eee625655a86cebcbad92e043/quad50"
  52 + standard_download="/7340/12345/71a669eee625655a86cebcbad92e043/standard"
  53 + portrait_download="/7340/12345/71a669eee625655a86cebcbad92e043/portrait"
  54 + medium_download="/7340/12345/71a669eee625655a86cebcbad92e043/medium"
  55 + small_download="/7340/12345/71a669eee625655a86cebcbad92e043/small"
  56 + quad16_download="/7340/12345/71a669eee625655a86cebcbad92e043/quad16"
  57 + large_download="/7340/12345/71a669eee625655a86cebcbad92e043/large"
  58 + quad75_download="/7340/12345/71a669eee625655a86cebcbad92e043/quad75">
  59 + <description>A multi-
  60 + line
  61 + description</description>
  62 + </section>
  63 + ...
52 64 </response>
  65 +
53 66
54 67 ### Example JSON Response
55 68
@@ -57,17 +70,27 @@ For non-public sites, the minimum level is:
57 70 "status": "ok",
58 71 "permission_level":"anonymous",
59 72 "cached":"1",
60   - "cache_time":"1291469615",
  73 + "cache_time":"1296413646",
61 74 "sections":[
62   - {"section_id": "101674", "start_time": "0", "title": "Earth",
63   - "description": "", "link": "/video/101353/101674/earth"},
64   - {"section_id": "102000", "start_time": "180", "title": "Wind",
65   - "description": "", "link": "/video/101353/102000/wind"},
66   - {"section_id": "101661", "start_time": "381", "title": "... and Fire",
67   - "description": "", "link": "/video/101353/101661/and-fire"}],
  75 + {"section_id": "12345", "start_time": "0",
  76 + "title": "It was the best of times",
  77 + "link": "/video/12345/12345/it-was-the-best-of-times",
  78 + "thumbnail_photo_id": "12345", "thumbnail_tree_id": "7340",
  79 + "thumbnail_token": "71a669eee625655a86cebcbad92e043",
  80 + "quad100_download": "/7340/12345/71a669eee625655a86cebcbad92e043/quad100",
  81 + "quad50_download": "/7340/12345/71a669eee625655a86cebcbad92e043/quad50",
  82 + "standard_download": "/7340/12345/71a669eee625655a86cebcbad92e043/standard",
  83 + "portrait_download": "/7340/12345/71a669eee625655a86cebcbad92e043/portrait",
  84 + "medium_download": "/7340/12345/71a669eee625655a86cebcbad92e043/medium",
  85 + "small_download": "/7340/12345/71a669eee625655a86cebcbad92e043/small",
  86 + "quad16_download": "/7340/12345/71a669eee625655a86cebcbad92e043/quad16",
  87 + "large_download": "/7340/12345/71a669eee625655a86cebcbad92e043/large",
  88 + "quad75_download": "/7340/12345/71a669eee625655a86cebcbad92e043/quad75",
  89 + "description": "A multi-\nline \ndescription"
  90 + }, ...],
68 91 "p": "1",
69 92 "size": "1",
70   - "total_count": "3",
71   - "site": { ... },
  93 + "total_count": "6",
  94 + "site": {...},
72 95 "endpoint": "/api/photo/section/list"
73 96 }

0 comments on commit c177981

Please sign in to comment.
Something went wrong with that request. Please try again.