Tout Developer Blog

I’ve been thinking a lot about hypermedia and how we can apply it to the Tout API. First thing that came to mind is pagination.

Now, we don’t handle pagination in the best way here at Tout. For instance, the production API will return a ‘pagination’ hash along with any collection view (streams, users, touts). We don’t really help you navigate that returned collection, you either have to:

• Make requests with an incrementing count and check the returned array everytime to see if it is empty (meaning you’ve reached the end of your collection)

OR

• Calculate the total number of pages by using ‘total_entries’ and ‘per_page’, and then write an iterative loop that ends with that number.

Either way, not ideal as you either have to write a calculating function or send extra network requests you don’t need.

So I’m trying to solve this problem for myself, and hopefully some of you, and whipped together a quick pagination implementation. You can access it at http://toutapi.herokuapp.com/streams/:stream_uid/touts and it transparently makes an API request to the production API and passes along the modified result. In the ‘pagination’ dictionary will be three new keys: 1. ‘total_pages’ 2. ‘next_page’ 3. ‘prev_page’

The last two are links (except in the case where you are at the end or beginning of the collection, respectively). This way you can simply make a request to the URL in the desired key without having to implement any logic in the client.

Since this does use the production API and is a transparent request proxy, you’ll need to provide a valid access_token with your request to the hypermedia implementation. You can utilize this app for any collection that returns Touts, so this includes a user’s Touts, a hashtag’s Touts or a stream’s Touts.

Please don’t hesitate to give me feedback!

Forms. We’re always filling out forms on the web, and sometimes we even upload files. We just select the file input (which now does awesome things on mobile!), choose and file and away it goes. Easy, right?

Try implementing your own multi-part form POST using Python straight out of the box, and its a different story. Here’s what it boils down to: its not that hard, but it is tedious and nobody does a great job of explaining how to implement it. And from here you have two choices: simply take a look at our Python client and how we implemented this multi-part form POST request or stay tuned.

For those following along at home, let’s start with the objective: we want to send binary data from a file to a server. Well, how do we normally make requests of a server? Most commonly, we use the URL and query string parameters. In fact, this is how web browsers make GET requests so you can view all the awesome interwebz. And this practice will work for most Tout API calls (though they won’t all be GET requests). There is one glaring hole in this statement, of course, and that is the Tout creation API call. It is a POST request to api.tout.com/api/v1/touts and if you use the tout[data] parameter then you’ll have to be making a multi-part POST request.

Ok, so we’re going to be making the request. Let’s figure out what we want the body of the request to look like. First and foremost, there is going to be a boundary that separates each parameter and the file data itself. And, just to be clear, this is an arbitrary boundary - you make make it whatever you want. For the client library we went with ‘—————bound@ry_$’. It doesn’t matter what you choose as long as its consistent across the whole request. But if the boundary is arbitrary, how does the server know what I’m using as the boundary? Well, you declare it at the beginning of the request.

Declare the content-type to be multipart and supply the boundary just like so:

Content-type: multipart/form-data, boundary=----------bound@ry_$

Note that we haven’t yet declared a content-length either, mainly because we don’t know how long the request will be yet! Alright, we’re done with the formalities of setting some headers, let’s move on to actually putting the data into the form. There are two potential types of fields we want to include in this request: text data or file data. Let’s start with the text data first. Start with your content-disposition declaration, and then supply the name of the field (I’ll use access_token in this example): content-disposition: form-data; name=”access_token”

Then comes something super insightful; a blank line. And then comes the actual value of the parameter, such as: e55b27892110869c1fdf0fba9afce06e1c8eb25742f8d3ce7bcf9ee9c59c4c23

Let’s put that all together in a blender, top it off with a boundary and we get: content-disposition: form-data; name=”access_token”

e55b27892110869c1fdf0fba9afce06e1c8eb25742f8d3ce7bcf9ee9c59c4c23
------------bound@ry_$--

We’re so close! Now we just need to adjust the above to handle the case where we have a file. Let’s play a little “Can you spot the difference?”

content-disposition: form-data; name="tout[data]"; filename="tout.mp4"
content-type: application/octet-stream

$binary_data_of_tout.mp4
------------bound@ry_$--

So where are the differences? First you also have a filename parameter that should equal the name of the file. In addition, a content type is declared and then just throw all the binary data where the value of the parameter goes.

What does the whole she! look like?

Content-type: multipart/form-data, boundary=----------bound@ry_$
Content-length: $length_of_request

------------bound@ry_$--
content-disposition: form-data; name="access_token"

e55b27892110869c1fdf0fba9afce06e1c8eb25742f8d3ce7bcf9ee9c59c4c23
------------bound@ry_$--
content-disposition: form-data; name="tout[data]"; filename="tout.mp4"
content-type: application/octet-stream

$binary_data_of_tout.mp4
------------bound@ry_$--

Not so hard once you get it, but a terrible process to troubleshoot. Hope this helps!

OAuth - just the sound of the word strikes fear into any developer who’s been playing around with web applications for the past 6 years. The whole workflow reeks of complication: messing with headers, nonces, it was a disaster.

So the developer community complained, and the spec committee heard.

And thus OAuth 2.0 was born, and everything most everything in the authentication world was righted.

Tout supports the OAuth 2.0 protocol with both implicit grant authorization as well as token grant authorization. This post will walk through the token grant process, but if you want to dive deeper into the differences, check back soon as we’ll be putting out another post on the reasons to use each.

There are only 5 pieces of information you need to successfully authenticate with Tout:

Authentication URL Response type Client ID Redirect URI Scope

The first one is always constant and will be https://www.tout.com/oauth/authorize

The next four are specific to your application and use case. As I said before, we’ll be doing a token grant process so response_type should equal “token”.

The client ID can be found under your application detail page. When you’re logged into the developer portal, click manage apps and then select an individual app to see the API key. This will be set as the value for the “client_id” parameter.

Next we’ll need to grab the redirect_uri from the the respective application. You submitted this when you registered the application and can change it as often as you’d like. The important thing to remember when you grab your redirect_uri is that it has to be URL-escaped. This likely means simply changing the “:” in “http://” to “http%3A//”. Once you’ve done that, this url-escaped value will be set to the ‘redirect_uri’ parameter.

Finally, you’ll want to specify the scope you want associated with the access token that will be returned to you. It can be any combination of:

read write share

Various API calls require different permissions, so make sure to include permissions for all the calls you plan on including. If you wish to add more than one permission to the request, separate them with “+” such as “read+write+share”.

Awesome, we have all the requisite pieces to make a successful OAuth request. Let’s put it all together into a single URL such as:

[https://www.tout.com/oauth/authorize?response_type=token& client_id=6f30e805cbe0e52934d5f28e13425d58fecdc27dc1618e7e702b538ebbbd90c3& redirect_uri=http%3A//localhost/tout.php& scope=read+write+share](https://www.tout.com/oauth/authorize?response_type=token& client_id=6f30e805cbe0e52934d5f28e13425d58fecdc27dc1618e7e702b538ebbbd90c3& redirect_uri=http%3A//localhost/tout.php& scope=read+write+share)

Go ahead and paste your URL into a browser window. You should be returned to the redirect_uri with a nice little present in the URL: an access_token. Supply that as a parameter to any API call that requires authentication and you’re good to go!

Happy authenticating. Make sure to check out the forums if you’re having issues :)

At the heart of the Tout service are Tout videos. In this post, you will learn one optimal approach to play Tout video within your browser-based application.

For the code example is this post, we will use Search for Touts. It’s a simple call that does not require authentication. This call allows you to search Touts based on a search term. You can pass parameters for the search term (q) as well as controlling pages returned (pages_returned) and pagination (page). Upon receiving the returned data, you’ll notice the Tout video assets, including poster images, size and mp4 link are nested within the Tout object.

Our engineering team recommends using Video.JS, an HTML video library, for displaying Tout videos within your web application. First, here is the full sample code:

In our review of this code, the first thing you will see is the reference to Video.js libraries in the of the code. This brings the stylesheets and javascript to render Video.js into the app.

In the , the first thing we have is a conditional checking for the search term we will ultimately pass when calling the Search for Touts method. Next, we write the REST call, plugging in the search parameter (q) and the optional (per_page) parameter for pagination of the results. Caling json_decode(file_get_contents($rest_url)); in the PHP code will run the REST call and handle the resulting data as JSON.

We can now parse through the returned JSON, casting each item as a Tout object. Getting properties out of the JSON is easy. $tout->tout->text displays the text description of the video.

Looping through each object, we will embed an instance of Video.JS dynamically adding the Tout video’s width, height, poster image and mp4 video itself. Finally, you can display other properties like created_at.

We recommend checking Video.js for browser compatability. You can also downlaod and host Video.JS on your own server.

All in all, a very easy code sample for displaying Tout videos. We will be posting many more code samples, so let us know what you want to see in our Forums. We look forward to seeing what you build with Tout video!

Welcome to the Tout Developer Center!

This site offers documentation, support and application management features for building Tout APIs into your applications. If you are a Tout user, you’re already aware of the powerful video posting and sharing features Tout provides. This site will let you learn about all these features and get you started registerting and managing your Tout integrated apps — which you will need to make authenticated calls to enable more advanced and secure user-based actions.

At the core of this site is documentation, forums and FAQs dedicated to supporting your integration of the Tout API. Our API exposes these features and more so you can build them into your applications. Tout APIs are broken into 3 groups: Search, Touts and Users. Search APIs include 3 different methods to search Touts. Each method returns a list of Tout objects which include data for displaying and playing Tout videos. Users APIs allow your app to add comprehensive functionality managing Tout users.

Most of these methods require authentication, which means the user must be logged into Tout via your app to change their user detail and associated data. You will also find methods in this group to list Touts posted and liked by the user.

Touts APIs is a set of methods allows your app to add comprehensive functionality creating, managing and listing Touts. Through methods in this API group, users of your app can do exciting things like post videos, reply to videos with their own (we call these conversations) and view Touts based on hashtags.

Over time the site will grow to include more example code, tools and even widgets to make Tout integration even easier. Our team is ready to support you through Forums and FAQs. Enjoy coding with the Tout API and we can’t wait to see what you build!

Oh, and don’t hesitate to reach out with questions or problems. Of course, compliments are always accepted too :)

-Jeremia & the Tout Developer Team jeremia@tout.com