log inhelp

Get your own free workspace
View
 

API

Page history last edited by Giovanni Cappellotto 1 year, 3 months ago Saved with comment

  1. Thounds public API
    1. Getting started
    2. Ruby example
      1. Register your application
      2. The OAuth session
      3. Authenticating for the first time
      4. Authenticate using existing access token

 

 

Thounds public API

 

Thounds API attempts to conform to the design principles of Representational State Transfer (REST). Requests and responses formats could be either XML or JSON according to client accepted content type.

 

Many of the Thounds API methods require user authentication. You can make authenticated requests using the Oauth protocol.

OAuth is a token-passing mechanism that allows users to control which application have access to their data without giving away their passwords. More information on the OAuth specification can be found at http://oauth.net.

 

 

Getting started

 

Follow this list to start hacking the Thounds platform.

 

  1. Follow @thounds (optional)
  2. Sign up or log in if you already have a Thounds account
  3. Register your application

 

More informations about the API could be found at Thounds API reference.

 

 

Ruby example

 

First of all you need ruby and the OAuth gem installed on your system.

 

 

Register your application

 

Log in to Thounds and go to http://thounds.com/oauth_clients/new.

 

Fill the form with details about your application:

 

The OAuth session

 

  1. start an interactive ruby shell 
    $ irb
  2. require the OAuth library 
    >> require 'oauth'
=> true 
  3. create new OAuth::Consumer instance 
    >> key = 'xxx'
=> "xxx"
>> secret = 'xxx'
=> "xxx"
>> c = OAuth::Consumer.new(key, secret, {:site => 'http://thounds.com'})
=> #<OAuth::Consumer:0x1010fba20 @key="xxx", @options={:access_token_path=>"/oauth/access_token", :oauth_version=>"1.0", :scheme=>:header, :signature_method=>"HMAC-SHA1", :proxy=>nil, :http_method=>:post, :request_token_path=>"/oauth/request_token", :site=>"http://thounds.com", :authorize_path=>"/oauth/authorize"}, @secret="xxx">

 

 

Authenticating for the first time

 

  1. get a request token from the OAuth provider (Thounds) 
    >> r = c.get_request_token
=> #<OAuth::RequestToken:0x10102cf40 @token="xxx", @params={:oauth_token_secret=>"xxx", "oauth_callback_confirmed"=>"true", "oauth_token_secret"=>"xxx", "oauth_token"=>"xxx", :oauth_token=>"xxx", :oauth_callback_confirmed=>"true"}, @consumer=#<OAuth::Consumer:0x10107b690 @key="xxx", @http=#<Net::HTTP thounds.com:80 open=false>, @http_method=:post, @options={:access_token_path=>"/oauth/access_token", :oauth_version=>"1.0", :scheme=>:header, :signature_method=>"HMAC-SHA1", :proxy=>nil, :http_method=>:post, :request_token_path=>"/oauth/request_token", :site=>"http://thounds.com", :authorize_path=>"/oauth/authorize"}, @secret="xxx">, @secret="xxx">
  2. get the authorization URL associated to the current request token 
    >> r.authorize_url
=> "http://thounds.com/oauth/authorize?oauth_token=xxx"
  3. authorize the request token

     
  4. get an OAuth::AccessToken from authorized request token 
    >> verifier = 'xxx'
=> "xxx"
>> a = r.get_access_token(:oauth_verifier => verifier)
=> #<OAuth::AccessToken:0x1018fac58 @token="xxx", @params={:oauth_token_secret=>"xxx", "oauth_token_secret"=>"xxx", "oauth_token"=>"xxx", :oauth_token=>"xxx"}, @consumer=#<OAuth::Consumer:0x10107b690 @key="xx", @http=#<Net::HTTP thounds.com:80 open=false>, @http_method=:post, @options={:access_token_path=>"/oauth/access_token", :oauth_version=>"1.0", :scheme=>:header, :signature_method=>"HMAC-SHA1", :proxy=>nil, :http_method=>:post, :request_token_path=>"/oauth/request_token", :site=>"http://thounds.com", :authorize_path=>"/oauth/authorize"}, @secret="xxx">, @secret="xx">
  5. test communication between consumer and provider 
    >> response = a.get('/profile', {'Accept' => 'application/xml'})
=> #<Net::HTTPOK 200 OK readbody=true>
>> puts response.body
<user>
  <default_thound>
    <lead_track_id>77881</lead_track_id>
    <public_url>http://thounds.com/t/a7a86b</public_url>
    <mix_url>http://thounds.com/thounds/39161/stream</mix_url>
    <bpm>130</bpm>
    <mix_duration>30</mix_duration>
    <public_id>a7a86b</public_id>
    <created_at>2010-10-26T19:27:52+02:00</created_at>
    <privacy>public</privacy>
    <tags>halloween2010 wow voice</tags>
    <video>false</video>
    <tracks>
      <track>
        <delay>0</delay>
        <cover nil="true"></cover>
        <uri>http://thounds.com/tracks/77881/stream</uri>
        <youtube_id nil="true"></youtube_id>
        <duration>0</duration>
        <lat nil="true"></lat>
        <host>s3</host>
        <created_at>2010-10-26T19:27:52+02:00</created_at>
        <lng nil="true"></lng>
        <privacy>public</privacy>
        <user>
          <city>Venice</city>
          <country>Italy</country>
          <avatar>http://s3.amazonaws.com/media.thounds.com/users/171/avatars/big/head.png?1266853826</avatar>
          <name>Giovanni</name>
          <id>171</id>
        </user>
        <thound_id>39161</thound_id>
        <tags>halloween2010 wow voice</tags>
        <id>77881</id>
        <offset>0</offset>
        <path>thounds/39161/tracks/77881.mp3</path>
        <user_id>171</user_id>
        <title>trasformer</title>
      </track>
    </tracks>
    <id>39161</id>
    <user_id>171</user_id>
  </default_thound>
  <is_new_user>false</is_new_user>
  <about nil="true"></about>
  <country>Italy</country>
  <city>Venice</city>
  <avatar>http://s3.amazonaws.com/media.thounds.com/users/171/avatars/original/head.png?1266853826</avatar>
  <site_url>http://www.focustheweb.com</site_url>
  <created_at>2009-07-01T14:41:33+02:00</created_at>
  <email>potomak84@gmail.com</email>
  <name>Giovanni</name>
  <tags>
    <tag>
      <name>Rock</name>
    </tag>
    <tag>
      <name>metal</name>
    </tag>
    <tag>
      <name>harcore</name>
    </tag>
  </tags>
  <blog_url>http://www.focustheweb.com</blog_url>
  <id>171</id>
</user>
=> nil

 

 

Authenticate using existing access token

 

  1. get OAuth::AccessToken from a valid access token attributes 
    >> key = 'xxx'
=> "xxx"
>> secret = 'xxx'
=> "xxx"
>> a = OAuth::AccessToken.new(c, token, secret)
=> #<OAuth::AccessToken:0x1018fac58 @token="xxx", @params={:oauth_token_secret=>"xxx", "oauth_token_secret"=>"xxx", "oauth_token"=>"xxx", :oauth_token=>"xxx"}, @consumer=#<OAuth::Consumer:0x10107b690 @key="xx", @http=#<Net::HTTP thounds.com:80 open=false>, @http_method=:post, @options={:access_token_path=>"/oauth/access_token", :oauth_version=>"1.0", :scheme=>:header, :signature_method=>"HMAC-SHA1", :proxy=>nil, :http_method=>:post, :request_token_path=>"/oauth/request_token", :site=>"http://thounds.com", :authorize_path=>"/oauth/authorize"}, @secret="xxx">, @secret="xx">
  2. test communication between consumer and provider 
    >> response = a.get('/profile', {'Accept' => 'application/xml'})
=> #<Net::HTTPOK 200 OK readbody=true>
>> puts response.body
<user>
  <default_thound>
    <lead_track_id>77881</lead_track_id>
    <public_url>http://thounds.com/t/a7a86b</public_url>
    <mix_url>http://thounds.com/thounds/39161/stream</mix_url>
    <bpm>130</bpm>
    <mix_duration>30</mix_duration>
    <public_id>a7a86b</public_id>
    <created_at>2010-10-26T19:27:52+02:00</created_at>
    <privacy>public</privacy>
    <tags>halloween2010 wow voice</tags>
    <video>false</video>
    <tracks>
      <track>
        <delay>0</delay>
        <cover nil="true"></cover>
        <uri>http://thounds.com/tracks/77881/stream</uri>
        <youtube_id nil="true"></youtube_id>
        <duration>0</duration>
        <lat nil="true"></lat>
        <host>s3</host>
        <created_at>2010-10-26T19:27:52+02:00</created_at>
        <lng nil="true"></lng>
        <privacy>public</privacy>
        <user>
          <city>Venice</city>
          <country>Italy</country>
          <avatar>http://s3.amazonaws.com/media.thounds.com/users/171/avatars/big/head.png?1266853826</avatar>
          <name>Giovanni</name>
          <id>171</id>
        </user>
        <thound_id>39161</thound_id>
        <tags>halloween2010 wow voice</tags>
        <id>77881</id>
        <offset>0</offset>
        <path>thounds/39161/tracks/77881.mp3</path>
        <user_id>171</user_id>
        <title>trasformer</title>
      </track>
    </tracks>
    <id>39161</id>
    <user_id>171</user_id>
  </default_thound>
  <is_new_user>false</is_new_user>
  <about nil="true"></about>
  <country>Italy</country>
  <city>Venice</city>
  <avatar>http://s3.amazonaws.com/media.thounds.com/users/171/avatars/original/head.png?1266853826</avatar>
  <site_url>http://www.focustheweb.com</site_url>
  <created_at>2009-07-01T14:41:33+02:00</created_at>
  <email>potomak84@gmail.com</email>
  <name>Giovanni</name>
  <tags>
    <tag>
      <name>Rock</name>
    </tag>
    <tag>
      <name>metal</name>
    </tag>
    <tag>
      <name>harcore</name>
    </tag>
  </tags>
  <blog_url>http://www.focustheweb.com</blog_url>
  <id>171</id>
</user>
=> nil

 

Comments (0)

You don't have permission to comment on this page.

PDF version