Spongecell API Documentation: Accessing the API using Ruby
This page discusses how to go about using Ruby to interact with the Spongecell API. You can use this as a model for understanding Sponger (this chapter is an explanation of some of its more basic parts), and by extension, for porting this functionality to other programming languages.
For an even more basic introduction to RESTful web APIs, check out our tutorial on interacting with our API using curl.
The tools we need
- You'll need to have Ruby installed to run these programs: http://www.ruby-lang.org/en/downloads/
- We'll need some Ruby libraries - they're included in the Ruby download itself, but we mention them so that you can check out their documentation:
The simplest Ruby program possible: retrieve an authorization token
Cut and paste this program into a file and save it as 'spongecell_api.rb' :
require 'net/http'
# We need three things to get an authorization token, as documented in
# http://localhost:3000/api/help/reference_documentation?resource=authorization_tokens
# 1) The URL to post the information to
url = "http://spongecell.com/api/authorization_tokens"
# 2) Your Spongecell user id
user_name = "<your spongecell login id>"
# 3) Your Spongecell password
password = "<your spongecell password>"
# Then, we can use the NET:HTTP library to perform a HTTP Post, retrieve the XML,
# and print it to the shell
puts Net::HTTP.post_form( URI.parse( url ), :user_name => user_name, :password => password ).body
Replace the
user_name
and
password
variables with your own Spongecell credentials, then run the program at your command line by typing
ruby spongecell_api.rb
You should see something like this (the program returns to us an XML document that contains an authorization token):
~/Desktop $ ruby spongecell_api_2.rb
<?xml version="1.0" encoding="UTF-8"?>
<authorization_token>
<calendar_id type="integer"></calendar_id>
<created_at type="datetime">2008-06-05T00:37:43Z</created_at>
<expires_at type="datetime"></expires_at>
<level>FULL</level>
<owner_id type="integer">50090</owner_id>
<remaining_uses type="integer"></remaining_uses>
<user_id type="integer">50090</user_id>
<value>oJv8IeIJE/bGSK6qlxBabpSA0SyG374oEYARxcYsWrmNHAwuN5EyIRrJyq87
/JZ7AZ60iqqSfsAs2gNk1s%2BlOENOmbr9HjQ54sRu6tm6EpwYMZw5DPG81N5S
RRNb0VQAHOW9%2BRID9J5vwWsxbV/IC7GuGc4lKPx5ViAvDQ/V9iBdWod5Q07C
iEkh7g1BPSm1U/tEany2hkPC/eKYzV1pzA==
</value>
<widget_id type="integer"></widget_id>
</authorization_token>
Extracting the token value from the XML
Next on the list is to extract the actual token value from the XML document. We'll modify our 1st program as follows, requiring the 'rexml' library, and then writing the three steps to create a new REXML document and parse out some data from the XML:
require 'net/http'
require 'rexml/document'
url = "http://spongecell.com/api/authorization_tokens"
user_name = "<your spongecell user name>"
password = "<your spongecell password>"
# We use the NET:HTTP library to perform a HTTP Post, retrieve the XML,
# and print it to the shell
xml_data = Net::HTTP.post_form( URI.parse( url ), :user_name => user_name, :password => password ).body
# Now, there are three steps to using the Ruby XML library to extract
# the authorization token from the XML
# 1: we create an REXML object using the XML data we have
doc = REXML::Document.new(xml_data)
# 2: we parse out a certain node (the token node)
elements = doc.get_elements("authorization_token/value").first
# 3: we parse out the text from the node
@token = elements.text if elements
puts "token: #{@token}"
Now, when we run this program at the command line, you'll see that we successfully extract the token value from the XML:
~/Desktop $ ruby spongecell_api.rb
token: oJv8IeIJE/bGSK6qlxBabpSA0SyG374oEYARxcYsWrmNHAwuN5EyIRrJyq87
/JZ7AZ60iqqSfsAs2gNk1s%2BlOENOmbr9HjQ54sRu6tm6EpwYMZw5DPG81N5S
RRNb0VQAHOW9%2BRID9J5vwWsxbV/IC4ttH90Q57/Y1Gfm2MFkht51i27sgQSa
sJjsF%2Bw7b8RLaogb1B8yqLIEwccb8sczqw==
Refactoring: making these steps into reusable building blocks
The program we've come up with is simple in the extreme. Let's refactor it to abstract out the actions that we'll be performing over and over again, so that eventually we'll have a set of building blocks that we can use to programatically access the Spongecell API.
require 'net/http'
require 'rexml/document'
HOST = "http://spongecell.com"
def login_and_get_token(user_name, password)
# the specific API path to be used (in a RESTful manner)
# to get our authorization
token_api_path = "/api/authorization_tokens"
# this line uses the Net::HTTP library to perform a HTTP Post and retrieve the XML
# returned
xml_data = post( token_api_path, :user_name=>user_name, :password=>password )
# these three lines use the REXML library to extract the token value out of the XML
# 1: we create an REXML object
doc = REXML::Document.new(xml_data)
# 2: we parse out a certain node (the token node)
elements = doc.get_elements("authorization_token/value").first
# 3: we parse out the text from the node and return it
@token = elements.text if elements
puts "token: #{@token}"
return @token
end
def post( url, args = {} )
args[:token] = @token if @token
url = HOST + url
puts "URL: " + url
puts "Posting data: #{args.inspect}"
return Net::HTTP.post_form(URI.parse(url),args).body
end
puts login_and_get_token("<replace with your user id>", "<replace with your password>")
In the above program, we've created two methods:
This method accepts a URL, and a set of arguments. The method posts the arguments to the URL, and returns any response.
This method accepts a name and password, and uses the post method, to post that information to spongecell's authorization token URL. The method then parses the authorization token out of the response and returns it.
Note also that we have moved Spongecell's host name out into a HOST constant.
So, when we run this program at the command line, we see that it accomplishes the same thing as before (it returns an authorization token). But, abstracting out methods like this ultimately will provide you with a framework for easily interacting with Spongecell's API.
Check out the SpongeR plugin for more examples. Tutorial: Sponger Rails Plug-in