Developers Documentation

Introduction

Part of the vision of Soocial is that our users can use their contact information wherever they need them. That also includes third party applications, thus we would like our users’’ contacts to be available to them where they use other apps. For this reason we have created an API, this page serves as the initial documentation of our API.

Soocial API

The Soocial API allows developers to integrate Soocial into their applications. It allows applications to access and modify Soocial data, and is implemented as Vanilla XML over HTTP. All clients that access and use the API are from a seen as another device in the Soocial ecosystem.

The API is a RESTful service. All data is available through the API as a resource to which can be referred using a unique identifier. It responds to a number of the HTTP methods, specifically GET, PUT, POST and UPDATE, and all responses from the API are in a simple XML format encoded as UTF-8.

Authentication

Authentication is realised using either OAuth or Basic HTTP authentication. Your Soocial.com username and password can be used as the authentication credentials for the API.

IMPORTANT: Depending on your url library you may need to escape your username and password before you connect. Your soocial username is an email address with an at sign (@) can cause problems because the at sign is sometimes used as a delimiter for the credentials and hostname.

http://user@domain.com:p4ssw0rd@www.soocial.com/contacts.xml

Escaping the username in ruby with CGI.escape(username) will avoid that problem. Most languages will have their own escape implementation so check the documentation.

http://user%40domain.com:p4ssw0rd@www.soocial.com/contacts.xml

You can request an OAuth token and find the needed URLs here.

Retrieving data from the API

To retrieve data you only need to do an HTTP GET on a resource identifier. For example, if you want to get all the contacts with cURL:

$ curl -u user%40domain.com:p4ssw0rd \\
    http://www.soocial.com/contacts/397.xml
>> <?xml version="1.0" encoding="UTF-8"?>
<contact>...</contact>

Pagination of the results is available when using the parameters page_num and page_size. When passing page_num in the parameters pagination will be used, the default page_size will be 20 contacts unless specified otherwise.

$ curl -u user%40domain.com:p4ssw0rd "http://www.soocial.com/contacts.xml\\
  ?page_num=1&page_size=10"
>> <?xml version="1.0" encoding="UTF-8"?>
<contacts type="array">...</contacts>

The total number of contacts available for the the user being logged in with is available under /user.xml. See the example below with ActiveResource below.

Getting a single contact:

$ curl -u user%40domain.com:p4ssw0rd \\
http://www.soocial.com/contacts/397.xml
>> <?xml version="1.0" encoding="UTF-8"?>
<contact type="array">...</contact>

All data is available according to the following resource paths:

• /contacts.xml
• /contacts/ID.xml
• /user.xml
• /users.xml
• /connections/phones.xml

Writing to the API

The API can be written to using the HTTP methods PUT, POST and DELETE in combination with the appropriate request headers.

Creating a new contact, using curl:

$ curl -u user%40domain.com:p4ssw0rd \\
    -d "contact[name][given]=Dennis&contact[name][family]=Jackson" \\
    http://www.soocial.com/contacts.xml -i
>> HTTP/1.1 201 Created
Location: http://www.soocial.com/contacts/414.xml
...

The response is an HTTP/1.1 201 Created with Location header indicating where the new contact resource can be found. Now we can add phone numbers to this contact, using curl:

$ curl -u user%40domain.com:p4ssw0rd -d \\
    "contact[name][given]=Dennis&contact[name][family]=Jackson&contact[TEL][new2]types[]=CELL&contact[TEL][new2][text]=+1 202-456-1111" \\
    http://www.soocial.com/contacts.xml -i
>> HTTP/1.1 201 Created
Location: http://www.soocial.com/contacts/415.xml
...

The response is a again an HTTP/1.1 201 Created with Location header indicating where the new contact can be found. If we want to delete that contact we can call its unique resource identifier (the URL) with the HTTP method DELETE, again with curl:

$ curl -u user%40domain.com:p4ssw0rd -X DELETE \\
    http://www.soocial.com/contacts/415.xml -i
>> HTTP/1.1 200 OK
...

The API returns an HTTP/1.1 200 OK and the contact is now deleted.

Dealing with the response and response status

All succesful operations respond with a status code of 200 OK or 201 Created depending on the operation. Sometimes a list, say GET /connections/phones.xml will not have any items, it will return an empty list.

Empty lists XML responses look like this, again with curl:

$ curl -u user%40domain.com:p4ssw0rd \\
    http://www.soocial.com/connections/phones.xml
>> <?xml version="1.0" encoding="UTF-8"?>
<nil-classes type="array"/>

Reserved fields

In contrast to the contact resources (/contacts/*), the resources for the user and the phone information only allow a limited set of operations, these are:

• /user.xml allows a full GET but only allows a PUT for the name field
• /users.xml allows a full GET but only returns the user info for the logged in user
• /connections/phones.xml and /connections/phones/ID.xml only allow GET

Consuming the API with ActiveResource

ActiveResource is a thin but powerful wrapper around RESTful services exposed by Ruby on Rails.

$ script/console
Loading development environment (Rails 1.2.4)
>> ActiveResource::Base.site = "http://www.soocial.com/"
=> "http://www.soocial.com/"
>> ActiveResource::Base.site.user = CGI.escape "user@domain.com"
=> "simon%40soocial.com"
>> ActiveResource::Base.site.password = CGI.escape "p4ssw0rd"
=> "p4ssw0rd"
>> class Contact < ActiveResource::Base; end
=> nil
>> Contact.find :first
=> #<Contact:0x262396c @prefix_options={}, @attributes={...}>
>> Contact.find :all
=> [#<Contact:0x274cfc8 @prefix_options={}, @attributes={...}, ...]
>> Contact.find(:all,:params => {:page_num => 1, :page_size => 5})
=> [#<Contact:0x274cfc8 @prefix_options={}, @attributes={...}, ...]
>> Contact.find(:all,:params => {:page_num => 1, :page_size => 5}).size
=> 5
>> class User < ActiveResource::Base; end
=> nil
>> user = User.find :first
=> #<User:0x344b080 @prefix_options={}, @attributes={...}>
>> user.invites_available
=> 5
>> user.number_of_contacts
=> 185

Inspired by 37 Signals ’’s Highrise wrapper, we’‘ve put together a small ruby wrapper for the API which sets up the ActiveResource models for you to play with in an IRB session:

$ SITE="http://user%40domain.com:p4ssw0rd@www.soocial.com" irb \\
    -r soocial_api_wrapper.rb

irb(main):001:0> millard = Soocial::Contact.find :first
irb(main):002:0> millard.first_name
=> "Millard"
irb(main):003:0>

Notes about the documentation

A few conventions have been applied in the documentation, these are:

• ID’s in a resource URL indicate that the resource’s unique ID needs to be inserted there
• ... indicates that unimportant bits of response data have been removed to eliminate noise from the documentation

All examples make use of cURL