OnSugar Developer Documentation

It's the OnSugar API!

The following documentation explains how to integrate OnSugar with your application over standard HTTP requests.

Versioning

Current version: 1.0

Available API Calls

Fetching content from OnSugar is easy: just append the API call to http://[sitename].onsugar.com/ and you'll get a structured version of your content in either JSON or XML. When using JSON the output will be sent as a Javascript object assigned to a variable named onsugar_api.

To access private methods you will need to authenticate your request by posting two additional arguments - login and password. Additionally, POST methods take an optional parameter callback which will return the response in either XML or JSON.

Public Methods

```
GET /api/posts/[format]
```
Last 25 posts
```
GET /api/posts/[format]/[id]
```
Post with the specified id
```
GET /api/user/[name]/[format]
```
User profile
```
GET /api/user/following/[name]/[format]
```
List of sites followed by a user
```
GET /api/followers/[format]
```
List of followers for a site

Private Methods

```
POST /api/posts/create
```
New post. See available post types for more information.
Arguments: type (text), login (text), password (text), callback (text)

Available Post Types

```
text
```
Arguments: title (text), body (html)
```
picture
```
Arguments: url, body (text)
```
chat
```
Arguments: title (text), body (text)
```
link
```
Arguments: url, body (text)
```
quote
```
Arguments: source (text), body (text)
```
video
```
Arguments: body (text), embed (html)

Errors

```
User does not exist.
```
Cause: The login passed to the API does not correspond to any OnSugar user.
```
Invalid credentials.
```
Cause: The login and password do not correspond to a user with permission to post to the site.

Examples

Javascript (Prototype with Cross-site AJAX plugin)

var mysite = "http://sugarcubes.onsugar.com/"
new Ajax.Request(mysite + "api/posts/create", {
    method: 'post',
    crossSite: true,
    parameters: {
        type: 'picture',
        login: 'mysugar',
        password: 'saccharin',
        url: 'http://www.craigslist.org/about/best/sdo/566171148.3.jpg',
        body: 'cat in a hat',
        callback: 'json'
    },
    onSuccess: function(transport) {
        eval(transport.responseText); //this gives us the onsugar_api object
        console.log("The URL for your new post is " + mysite + onsugar_api["posts"][0].id);
    }
});

Ruby on Rails (using Hpricot)

@doc = Hpricot(Net::HTTP.get(URI.parse("http://sugarcubes.onsugar.com/api/posts/xml")))
(@doc/:post).each do |post|
    @posts << Post.create!(:title => (post/:title).innerHTML,
                           :body => (post/:body).innerHTML)
end