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: title (text), url, caption (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

Note that fetching data from or related to private blogs is currently unsupported.