Spongecell API Documentation: Accessing the API using Curl

In this article we introduce a very simple method for interacting with the Spongecell API: cURL, a command line tool for interacting with HTTP web services. The point of this is to provide to readers a gentle introduction to interacting with RESTful web services.

If this is too simple for you, feel free to check out the more advanced tutorial, Accessing the API using Ruby or, skip ahead to the reference documentation.

Make sure cURL is installed / install cURL

In the end we will be using computer programs to talk to the API. But it's necessary to first understand how the calls to the API are made, and responses returned. A simple way to learn how to interact with the API is to use the command line utility cURL.

From Wikipedia:
"cURL is a command line tool for transferring files with URL syntax ... it is a good tool for simulating a user's actions at a web browser."
http://en.wikipedia.org/wiki/CURL

cURL is available for just about every operating system in existence. It may be already available on your operating system. Open a terminal window and enter curl -V (note the capital V which is necessary). 

~/Desktop $ curl -V 
                curl 7.16.1 (i386-apple-darwin8.11.1) libcurl/7.16.1 OpenSSL/0.9.8e zlib/1.2.3
                Protocols: tftp ftp telnet dict ldap http file https ftps 
                Features: Largefile NTLM SSL libz

If instead, you see 'syntax error' or 'program not found' - you need to download and install cURL at this address: http://curl.haxx.se/dlwiz/?type=bin

Retrieve the Spongecell home page using cURL

The point of cURL is to let us use the API in a very simple manner so as to learn some fundamental lessons. Let's get started by requesting something very simple: the HTTP of the Spongecell home page. At your terminal window, enter this command: 

~/Desktop $ curl -v http://spongecell.com

The --verbose (shortcut -v) option tells cURL to show you detailed information about the HTTP connections it is making. This is quite useful for getting your mind around the concepts at play here.

We get back the HTML of our home page. If we were in a browser, the browser would render this HTML into the beautiful Spongecell home page. However, at the command prompt, we just see the raw HTML: 

~/Desktop $ curl -v http://spongecell.com
                * About to connect() to spongecell.com port 80 (#0)
                *   Trying 65.74.180.72... connected
                * Connected to spongecell.com (65.74.180.72) port 80 (#0)
                > GET / HTTP/1.1
                ...
                > 
                < HTTP/1.1 200 OK
                < Server: nginx/0.6.28
                < Date: Thu, 05 Jun 2008 00:55:00 GMT
                <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
                <html lang='en-US' xml:lang='en-US' xmlns='http://www.w3.org/1999/xhtml'>
                  <head>
                    <meta content='text/html;charset=utf-8' http-equiv='Content-Type' />
                    <title>Event Marketing | Online Calendar | Spongecell</title>
                ...

Authenticate to the API

In order to do anything interesting, we need to authenticate to the API. You can read the Spongecell reference documentation about authentication here: Resource: Authorization Tokens

The easiest and most direct way is to send your User ID and password to the API and receive an authorization token in return. You include this token in further requests to let the API know who you are, and that you are a trusted person. This token expires 1 hour after it's issued to you, so you have to periodically refresh it.

Issue this at your command prompt (filling in the user name and password with your own Spongecell account credentials): 

~/Desktop $ curl --data "user_name=<your user ID>&password=<your password>" http://spongecell.com/api/authorization_tokens

That will return to us some XML which includes an authorization token (note the hash between the <value> tags): 

~/Desktop $ curl --data "user_name=<your user name>&password=<your password>" http://spongecell.com/api/authorization_tokens
                <?xml version="1.0" encoding="UTF-8"?>
                <authorization_token>
                  <calendar_id type="integer"></calendar_id>
                  <created_at type="datetime">2008-06-05T01:04:52Z</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
                RRNb0VQAwTThRzJWJF%2Bcqkh5m84rlPPzo4/iN1IagQ/Y1lnZoqI50j8Jo7FS
                XPkVVI5xKDztCEGjQDUcbRQC7M72QkJZJw==
                </value>
                  <widget_id type="integer"></widget_id>
                </authorization_token>

Using the token, view a list of the calendars in the account

Copy out the authorization token, and we'll use it to retrieve a list of the Spongecell calendars associated with your account. Issue the following command, noting how we append ?token=<the token value> to the API call: 

~/Desktop $ curl http://spongecell.com/api/calendars?token=oJv8IeIJE/bGSK6qlxBabpSA0SyG374oEYARxcYsWrmNHAwuN5EyIRrJyq87/JZ7AZ60iqqSfsAs2gNk1s%2BlOENOmbr9HjQ54sRu6tm6EpwYMZw5DPG81N5SRRNb0VQAwTThRzJWJF%2Bcqkh5m84rlMrr35LefMM4Dite4hhesPUEyrtYQDan119SGIWvzWfkBL9wWQIRExyH3yMsMHyMOg==

If instead you see a message "This method requires an authorized user with a verified e-mail address." - see instructions in the getting started section.

If the call fails with message "Unable to decrypt Authorization Token", experiment with editing the token to remove any carriage returns.

We get back some XML that looks like this: 

~/Desktop $ curl http://spongecell.com/api/calendars?token=oJv8IeIJE/bGSK6qlxBabpSA0SyG374oEYARxcYsWrmNHAwuN5EyIRrJyq87/JZ7AZ60iqqSfsAs2gNk1s%2BlOENOmbr9HjQ54sRu6tm6EpwYMZw5DPG81N5SRRNb0VQAwTThRzJWJF%2Bcqkh5m84rlMrr35LefMM4Dite4hhesPUEyrtYQDan119SGIWvzWfkBL9wWQIRExyH3yMsMHyMOg==
                <?xml version="1.0" encoding="UTF-8"?>
                <calendars>
                  <calendar>
                    <description></description>
                    <id type="integer">48713</id>
                    <name>spongecell</name>
                    <scml_event_page_id type="integer"></scml_event_page_id>
                    <creator_name>Kevin Trowbridge</creator_name>
                    <rss_url>http://spongecell.com/rss/events/kmtrowbr/spongecell</rss_url>
                    <ics_url>http://spongecell.com/ics/calendar/kmtrowbr/spongecell</ics_url>
                  </calendar>
                  <calendar>
                    <description></description>
                    <id type="integer">48721</id>
                    <name>birthdays - gCalendar</name>
                    <scml_event_page_id type="integer"></scml_event_page_id>
                    <creator_name>Kevin Trowbridge</creator_name>
                    <rss_url>http://spongecell.com/rss/events/kmtrowbr/birthdays+-+gCalendar</rss_url>
                    <ics_url>http://spongecell.com/ics/calendar/kmtrowbr/birthdays+-+gCalendar</ics_url>
                  </calendar>
                  ...

If at any point during the tutorial, you receive an "Authorization Token has expired" response you need to re-authenticate yourself to the API and get a new authorization token. Tokens expire after 1 hour.

Get more information about a calendar

From looking closely at the last set of XML that was returned, we see that one of the calendars has an ID number of 48713. According to the API documentation Resource: Calendars we can view 'an expanded set of fields' if we 'GET' the path /api/calendars/<calendar id>

So let's take a look at the 'expanded set of fields' for the calendar # 48713: 

~/Desktop $ curl http://spongecell.com/api/calendars/48713?token=oJv8IeIJE/bGSK6qlxBabpSA0SyG374oEYARxcYsWrmNHAwuN5EyIRrJyq87/JZ7AZ60iqqSfsAs2gNk1s%2BlOENOmbr9HjQ54sRu6tm6EpwYMZw5DPG81N5SRRNb0VQAwTThRzJWJF%2Bcqkh5m84rlMrr35LefMM4Dite4hhesPUEyrtYQDan119SGIWvzWfkBL9wWQIRExyH3yMsMHyMOg==
                <?xml version="1.0" encoding="UTF-8"?>
                <calendar>
                  <description></description>
                  <id type="integer">48713</id>
                  <name>spongecell</name>
                  <scml_event_page_id type="integer"></scml_event_page_id>
                  <creator_name>Kevin Trowbridge</creator_name>
                  <rss_url>http://spongecell.com/rss/events/kmtrowbr/spongecell</rss_url>
                  <ics_url>http://spongecell.com/ics/calendar/kmtrowbr/spongecell</ics_url>
                  <can_add_to>true</can_add_to>
                  <can_edit>true</can_edit>
                  <events>
                    <event>
                      <created_on type="datetime">2007-10-29T23:56:11-07:00</created_on>
                      <description></description>
                      <id type="integer">480205</id>
                      <image_url></image_url>
                      <location></location>
                      <location_name></location_name>
                      <ticket_url></ticket_url>
                      <title>New Year's</title>
                      <updated_on type="datetime">2007-10-29T23:56:11-07:00</updated_on>
                      <promote type="boolean">false</promote>
                      <time_zone>New York</time_zone>
                      <tag_list></tag_list>
                      <attending type="boolean">true</attending>
                      <all_day type="boolean">true</all_day>
                <start_time type="datetime">2002-01-01T00:00:00-05:00</start_time><end_time type="datetime">2002-01-01T23:59:00-05:00</end_time><primary_calendar_id>48713</primary_calendar_id>      <resources>
                      </resources>
                      <videos>
                      </videos>
                      <event_page_url>http://spongecell.com/event/view/480205</event_page_url>
                      <facebook_add_url>http://apps.facebook.com/spongecell_flyr/add_event/480205</facebook_add_url>
                      <myspace_add_url>http://spongecell.com/api/events/480205/add_to_myspace</myspace_add_url>
                      <can_edit>true</can_edit>
                    </event>
                ...

Ah ha! Wow, it lists all kinds of information about the calendar, including any/all of the events on the calendar.

Create an event

To continue our exploration of the Spongecell API, let's create an event in that calendar. We read in the help pages (see the API documentation Resource: Events ) that we can get a list of the required fields by issuing an HTML GET request to the url /api/events/new

GET is curl's default HTTP option (so we don't need to issue any special parameters to curl) ... we'll simply type curl, followed by http://spongecell.com/api/events/new

Retrieving a list of required fields has nothing to do with our account, specifically, so - in this case - we can leave off the authorization token. 

~/Desktop $ curl http://spongecell.com/api/events/new
                <?xml version="1.0" encoding="UTF-8"?>
                <event>
                  <description></description>
                  <image_url></image_url>
                  <location></location>
                  <location_name></location_name>
                  <ticket_url></ticket_url>
                  <title></title>
                  <time_zone></time_zone>
                  <all_day type="boolean">false</all_day>
                  <resources>
                  </resources>
                  <videos>
                  </videos>
                  <event_page_url>http://spongecell.com/event/view/</event_page_url>
                  <facebook_add_url>http://apps.facebook.com/spongecell_flyr/add_event/</facebook_add_url>
                  <myspace_add_url>http://spongecell.com/api/events//add_to_myspace</myspace_add_url>
                </event>

So, now we know which fields are available to us, as we create the new event. The API documentation Resource: Events tells us that we have to POST the information to /api/events : Create_event_documentation

We type 'curl --help' to see the options available for curl. One of which is: -d/--data HTTP POST data (H)

Now we can go about assembling the command line incantation to allow us to create an event - we'll only specify the required fields:

Field name URL escaped data
title Bathtime
description I%20am%20dirty
location The%20bathtub
calendar_id 48713

Note how we have to escape certain characters, such as spaces. You can read more about this type of escaping here: http://en.wikipedia.org/wiki/Percent-encoding

We take this information and place it inside of the curl request like this:

curl -d "title=Bathtime&description=I%20am%20dirty&location=The%20bathtub&calendar_id=48713" http://spongecell.com/api/events?token=<token value>

Here we can see the command line being executed and the response that's returned: 

~/Desktop $ curl -d "title=Bathtime&description=I%20am%20dirty&location=The%20bathtub&calendar_id=153433" http://spongecell.com/api/events?token=oJv8IeIJE/bGSK6qlxBabpSA0SyG374oEYARxcYsWrmNHAwuN5EyIRrJyq87/JZ7AZ60iqqSfsAs2gNk1s%2BlOENOmbr9HjQ54sRu6tm6EpwYMZw5DPG81N5SRRNb0VQAfYxaabZGed1sHrLAP2d%2B97RrujKAnyqcDmxDLrAXHQLW5g/Tfb/7DLbxU2jsihDo0iJ/Vk%2Bs2DNh/4ZCL4/M5Q==
                <?xml version="1.0" encoding="UTF-8"?>
                <event>
                  <created_on type="datetime">2008-06-04T19:27:15-07:00</created_on>
                  <description>I am dirty</description>
                  <id type="integer">675237</id>
                  <image_url></image_url>
                  <location>The bathtub</location>
                  <location_name></location_name>
                  <ticket_url></ticket_url>
                  <title>Bathtime</title>
                  <updated_on type="datetime">2008-06-04T19:27:15-07:00</updated_on>
                  <promote type="boolean">true</promote>
                  <time_zone>Los Angeles</time_zone>
                  <tag_list></tag_list>
                  <attending></attending>
                  <all_day type="boolean">false</all_day>
                <start_time type="datetime">2008-06-04T19:27:15-07:00</start_time><end_time type="datetime">2008-06-04T19:27:15-07:00</end_time><primary_calendar_id>153433</primary_calendar_id>  <resources>
                  </resources>
                  <videos>
                  </videos>
                  <event_page_url>http://spongecell.com/event_page/view/675237</event_page_url>
                  <facebook_add_url>http://apps.facebook.com/spongecell_flyr/add_event/675237</facebook_add_url>
                  <myspace_add_url>http://spongecell.com/api/events/675237/add_to_myspace</myspace_add_url>
                </event>

Now, if you login to you Spongecell account in your browser - you'll see the event has appeared within the Spongecell interface:

Event_created_with_api

Rename the event

Another type of operation is an update, which requires an HTML PUT.

You can always tell curl which type of HTML request to use with the parameter: '--request XXX' , in this case, we'll use '--request PUT'

This request will change the event's title from 'Bathtime' to 'Spongebath'. Note the number in the URL: /api/events/675237 We got this number from the 'event_id' attribute that was in the XML that the API returned when the event was created (see previous section above). 

curl --request PUT -d "title=Spongebath" http://spongecell.com/api/events/675237?token=oJv8IeIJE/bGSK6qlxBabpSA0SyG374oEYARxcYsWrmNHAwuN5EyIRrJyq87/JZ7AZ60iqqSfsAs2gNk1s%2BlOENOmbr9HjQ54sRu6tm6EpwYMZw5DPG81N5SRRNb0VQAfYxaabZGed1sHrLAP2d%2B97RrujKAnyqcDmxDLrAXHQLW5g/Tfb/7DLbxU2jsihDo0iJ/Vk%2Bs2DNh/4ZCL4/M5Q==

When we execute this command, we'll see the new XML of the event returned, which includes the changed title: 

~/Desktop $ curl --request PUT -d "title=Spongebath" http://spongecell.com/api/events/675237?token=oJv8IeIJE/bGSK6qlxBabpSA0SyG374oEYARxcYsWrmNHAwuN5EyIRrJyq87/JZ7AZ60iqqSfsAs2gNk1s%2BlOENOmbr9HjQ54sRu6tm6EpwYMZw5DPG81N5SRRNb0VQAfYxaabZGed1sHrLAP2d%2B97RrujKAnyqcDmxDLrAXHQLW5g/Tfb/7DLbxU2jsihDo0iJ/Vk%2Bs2DNh/4ZCL4/M5Q==
                <?xml version="1.0" encoding="UTF-8"?>
                <event>
                  <created_on type="datetime">2008-06-04T19:27:15-07:00</created_on>
                  <description>I am dirty</description>
                  <id type="integer">675237</id>
                  <image_url></image_url>
                  <location>The bathtub</location>
                  <location_name></location_name>
                  <ticket_url></ticket_url>
                  <title>Spongebath</title>
                  <updated_on type="datetime">2008-06-04T19:34:10-07:00</updated_on>
                  <promote type="boolean">true</promote>
                  <time_zone>Los Angeles</time_zone>
                  <tag_list></tag_list>
                  <attending></attending>
                  <all_day type="boolean">false</all_day>
                <start_time type="datetime">2008-06-04T19:34:10-07:00</start_time><end_time type="datetime">2008-06-04T19:34:10-07:00</end_time><primary_calendar_id>153433</primary_calendar_id>  <resources>
                  </resources>
                  <videos>
                  </videos>
                  <event_page_url>http://spongecell.com/event_page/view/675237</event_page_url>
                  <facebook_add_url>http://apps.facebook.com/spongecell_flyr/add_event/675237</facebook_add_url>
                  <myspace_add_url>http://spongecell.com/api/events/675237/add_to_myspace</myspace_add_url>
                </event>

So now, if you refresh your browser that is logged into the Spongecell UI, you'll see that the event has indeed been renamed:

Event_renamed_with_api

Delete the event

For the final bit of our introduction to the API, we'll delete the event. Predictably enough, this requires an HTTP 'DELETE' 

~/Desktop $ curl --request DELETE http://spongecell.com/api/events/675237?token=oJv8IeIJE/bGSK6qlxBabpSA0SyG374oEYARxcYsWrmNHAwuN5EyIRrJyq87/JZ7AZ60iqqSfsAs2gNk1s%2BlOENOmbr9HjQ54sRu6tm6EpwYMZw5DPG81N5SRRNb0VQAfYxaabZGed1sHrLAP2d%2B97RrujKAnyqcDmxDLrAXHQLW5g/Tfb/7DLbxU2jsihDo0iJ/Vk%2Bs2DNh/4ZCL4/M5Q==

The API returns information about the event that was deleted. But, let's verify that the event no longer exists by trying to view its details again: 

~/Desktop $ curl --request GET http://spongecell.com/api/events/675237?token=oJv8IeIJE/bGSK6qlxBabpSA0SyG374oEYARxcYsWrmNHAwuN5EyIRrJyq87/JZ7AZ60iqqSfsAs2gNk1s%2BlOENOmbr9HjQ54sRu6tm6EpwYMZw5DPG81N5SRRNb0VQAfYxaabZGed1sHrLAP2d%2B97RrujKAnyqcDmxDLrAXHQLW5g/Tfb/7DLbxU2jsihDo0iJ/Vk%2Bs2DNh/4ZCL4/M5Q==
                Not authorized for specified event.

Well - it doesn't seem to exist. Success!