Simple Client Libraries

Rdio-Simple is a collection of simple client libraries for the Rdio Web Service API.

There are currently libraries for PHP, Python and Ruby. They have minimal external dependencies and are simple to use. They provide a simple API that is simliar across all of the languages. It's available from github:
https://github.com/rdio/rdio-simple

To install the libraries simply copy the rdio-simple files into your app's source code:  

PHP:

cp rdio-simple/om.php rdio-simple/rdio.php my-app/

Python:

cp rdio-simple/om.py rdio-simple/rdio.py my-app/

Ruby:

cp rdio-simple/om.rb rdio-simple/rdio.rb my-app/

Load the Rdio object from the library:  

PHP:

require_once 'rdio.php';

Python:

from rdio import Rdio

Ruby:

require 'rubygems' # so that the JSON gem is available
require 'rdio'

Instantiate an Rdio object with consumer credentials and optionally an OAuth token:  

PHP:

$rdio = new Rdio(array("consumerkey", "consumersecret"));
# or
$rdio = new Rdio(array("consumerkey", "consumersecret"), array("token", "tokensecret"));

Python:

rdio = Rdio(("consumerkey", "consumersecret"))
# or
rdio = Rdio(("consumerkey", "consumersecret"), ("token", "tokensecret"))

Ruby:

rdio = Rdio.new(["consumerkey", "consumersecret"])
# or
rdio = Rdio.new(["consumerkey", "consumersecret"], ["token", "tokensecret"])

Make Rdio API calls by calling the "call" method on the Rdio instance. Pass arguments as a dictionary:

PHP:

$ian = $rdio->call("findUser", array("vanityName" => "ian"));
if ($ian->status == "ok") {
  print $ian->result->firstName." ".$ian->result->lastName."\n";
} else {
  print "ERROR: ".$ian->message."\n";
}

Python:

ian = rdio.call("findUser", {"vanityName": "ian"})
if (ian["status"] == "ok"):
  print ian["result"]["firstName"] + " " + ian["result"]["lastName"]
else:
  print "ERROR: " + ian["message"]

Ruby:

ian = rdio.call("findUser", {"vanityName" => "ian"})
if (ian["status"] == "ok")
  puts ian["result"]["firstName"] + " " + ian["result"]["lastName"]
else
  puts "ERROR: " + ian["message"]
end

Authentication is a two phase process. First call the "begin authentication" method with a callback, either an URL or "oob" to use the OAuth PIN flow.  

PHP:

$auth_url = $rdio->begin_authentication($callback);

Python:

auth_url = rdio.begin_authentication(callback)

Ruby:

auth_url = rdio.begin_authentication(callback)

The Rdio object's token field will be set to the OAuth request token. If authentication will be completed with a different Rdio object instance (for example in a traditional web flow) then the token should be saved and passed into the constructor:

PHP:

$saved_token = $rdio->token # a two element array
# later...
$rdio = new Rdio(array("consumerkey", "consumersecret"), $saved_token);

Python:

saved_token = rdio.token # a two element tuple
# later...
rdio = Rdio(("consumerkey", "consumersecret"), saved_token)

Ruby:

saved_token = rdio.token # a two element array
# later...
rdio = Rdio.new(["consumerkey", "consumersecret"], saved_token)

Direct the user to load that auth_url. Once they've approved the application they will be shown a PIN to enter, or directed to the callback URL provided with a query-string parameter called oauth_verifier. We refer to that PIN or parameter as the verifier. Pass that to the "complete authentication" method:

PHP:

$rdio->complete_authentication(verifier);

Python:

rdio.complete_authentication(verifier)

Ruby:

rdio.complete_authentication(verifier)

The token field will now contain an OAuth access token that can be used in the future so that the app can act as the user without needing to go through the authentication process again. It can be saved and restored just like the request token above.