Getting Started Guide

This guide takes you through the process of accessing the Miso API in your web or mobile application. If you’re familiar with any of the common OAuth RESTful APIs that exist today (Twitter, Foursquare, Yelp, Mashable, etc.), this should all be very familiar. If you’re not, it’s fairly easy, and there are a lot of libraries and sample code out there to help you.

Step 1: Register New Application

You’ll need to register your application with Miso to get your unique Application Key. Click on “Manage Applications” in the upper right hand corner of this page, screenshot below.

Getting_started

Click on “Register an Application” and fill out the form. The callback URL is the address a user will be redirected to after they authenticate with Miso. If you’re creating a mobile application, you don’t need to specify a callback URL here.

Step 2: Authenticate User

You’ll want users to authorize your application to read their check-in history or to check-in to a TV show or movie. Miso uses OAuth for authentication. The ways of OAuth are mysterious, but play along, and you’ll get what you need. In order to authenticate a user in your application, you’ll need to do the following:

  1. Get a request token from Miso.
  2. Send the user to the Miso authentication page.
  3. Get an access token for that user from Miso.

There are OAuth libraries available for most major languages that make it easy to get request and access tokens. Check out the sample application to see this process in action. Read more about OAuth here.

Step 3: Access REST API

Once you have the access token for a user, you can access the REST API to get a user's recent check-ins or to create a new check-in. For example, to get a user's recent check-ins:

  1. Authenticate the user and get an access token.
  2. Perform an HTTP GET to the checkins resource.

To create a new check-in:

  1. Authenticate the user and get an access token.
  2. Perform an HTTP GET to the media resource and pick the appropriate media id.
  3. Perform an HTTP POST to the checkins resource with the media id.

All HTTP GET and POST requests need to be generated via the OAuth library that you're using because they have to be signed in a certain way. Check out the sample application to see this process in action. Read more about the available REST resources here.

Step 4: Get Support

API not working as you expect? If you have any questions/comments/requests, email us or, better yet, post in our developers discussion forum. Click here for details.

A Sample Application

To see this in action, we've created a simple Sinatra web application that you can download and try. Sinatra is a popular Ruby web framework that's perfect for building simple (and complex) web applications. It's very easy to set up locally.

For the impatient:

  1. Complete Step 1 above to get your application key and secret.
  2. Install Sinatra by typing `gem install sinatra` in your terminal.
  3. Download miso_api_demo.rb.
  4. Type `ruby miso_api_demo.rb` in your shell.

The details:

Besides the basic gems used for Ruby and Sinatra, we also include a popular Ruby OAuth client, more info found here.

require 'rubygems'
require 'sinatra'
require 'oauth'
require 'json'

For the purposes of this application, we temporarily store some tokens in a cookie for us to access later. In a real application, this data would probably go into a database. The following snippet enables cookie-based sessions for our Sinatra app.

enable  :sessions

The following global variables are required for the authentication process. The consumer key and secret are acquired as part of Step 1 above. For this sample application, the callback URL is on the localhost.

MISO_CONSUMER_KEY = <YOUR CONSUMER KEY>
MISO_CONSUMER_SECRET = <YOUR CONSUMER SECRET>
MISO_SITE = "http://gomiso.com"
MISO_CALLBACK_URL="http://localhost:4567/oauth/callback"

Every request is signed using your unique consumer key and consumer secret. Commonly, OAuth libraries will have a consumer object for convenience. Consumer objects can generate request and access tokens.

def consumer
  OAuth::Consumer.new MISO_CONSUMER_KEY, MISO_CONSUMER_SECRET, :site => MISO_SITE
end

The following snippet creates a simple landing page for the demo application.

get "/" do
  "Click <a href='/oauth/connect'>here</a> to connect to Miso API through OAuth"
end

The following snippet gets a request token, saves it for later in a cookie, and redirects the user to the Miso authentication URL where they will log in.

get "/oauth/connect" do
  @request_token = session[:request_token] =
    consumer.get_request_token(:oauth_callback => MISO_CALLBACK_URL)
  redirect @request_token.authorize_url
end

After the user authenticates to Miso, they will be redirected to the callback URL where we can use the original request token and the oauth verifier to request an access token. Almost there!

get "/oauth/callback" do
  @request_token = session[:request_token]
  @access_token = session[:access_token] =
    @request_token.get_access_token(:oauth_verifier => params[:oauth_verifier])
  redirect "/oauth/user"
end

Finally, we can use the access token to access the REST resources. Note that they must be accessed via the OAuth library because each request must be signed. In the sample application, we retrieve some information about the user and their most recent check-in.

get "/oauth/user" do
  @access_token = session[:access_token]

  user = get_json_hash("/api/oauth/v1/users/show.json")['user']
  checkins = get_json_hash("/api/oauth/v1/checkins.json?user_id=#{user['id']}")
  checkin = checkins.first['checkin']

  html = "<img src='#{user['profile_image_url']}' /><br/>"
  html << "#{user['full_name']} (#{user['username']})<br/>"
  html << "Last checked into: #{checkin['media_title']}<br/>"
  html << "<img src='#{checkin['media_poster_url']}' />"
end

Download the entire source file here.