Tuesday Oct 21, 2008

SocialSite REST API not so RESTful

So says Roy Fielding, the author of the paper that defined REpresentational State Transfer (REST). And the same goes for the OpenSocial REST API, which is the basis for the SocialSite REST APIs. Here's part of his comment about OpenSocial:

Roy Fielding: The OpenSocial RESTful protocol is not RESTful. It could be made so with some relatively small changes, but right now it is just wrapping RPC results in common Web media types.

There are lots of advantages to being RESTful and we certainly want both the OpenSocial and the SocialSite REST APIs to live up to their names, so I'm glad to hear the changes are "relatively small." Now we just need to figure out what those changes are. I asked Roy to elaborate and I also started a thread (Google Groups login required) on the topic in the OpenSocial spec discussion group.

Monday Oct 06, 2008

On The Horizon: A Portable Contacts API?

Picture of a Rolodex

Want to invite your email contacts to join you on your favorite social networking site? You probably can. Want to do so without having to give your email account username and password to the social networking site? Your odds drop a bit. Want to do it all in a standardized way? Your odds drop to zero.

But that could change, if the guys behind the Portable Contacts effort have their way. They're trying to provide a standardized and secure way for users to share address book data across different sites.

The specification is still at the draft stage. But, as Dare Obasanjo describes, there is already a lot to like about its approach (particularly the alignment with OAuth and OpenSocial). So while it's too early for a social networking server like Project SocialSite to directly leverage this work, we'll certainly be keeping an eye on it.

Friday Oct 03, 2008

Project SocialSite Turns One (Milestone) Today

We've reached our first milestone release, available on the download page now. While you won't see many changes on the surface, that doesn't mean a lot hasn't changed. Our Milestone 1 release includes a complete rewrite of many of our back-end services to use the new OpenSocial REST and JSON-RPC APIs.

For more information on the REST API Dave has a great writeup in this blog. These changes give us a better alignment with OpenSocial, allow us to batch requests, and make it easier to support multiple forms of client to server and server to server communication. With these changes in the back end completed, we can focus our attention now towards UI improvements and new features. As always, let us know what you like, what you'd like to see, and especially let us know if you'd like to help!

Wednesday Sep 24, 2008

Details of REST Implementation (Java) in Shindig

A while back Dave Johnson posted a nice overview detailing how the REST API works in Apache Shindig. He just updated that to cover Shindig/Java's latest REST/RPC implementation.

For those interested in more, here is an article that delves into much more details on this topic.

Tuesday Sep 16, 2008

Finalizing SocialSite REST API - Proposal

As we mentioned last week, we are currently working on implementing complete support for OpenSocial RESTful API specification. We have published a formal proposal here that details how we are planning to achieve this. Feedback is most welcome.

Wednesday Sep 03, 2008

Exploring Project SocialSite's REST API

Duke the explorer

Project SocialSite is still young, and we're working on more documentation as well as our implementation. In the meantime, you might feel like doing a little exploration yourself. In his blog "exploring a web 2.0 app" Henry Story shares his methods and findings. While this approach can be very helpful in understanding how SocialSite works, the interfaces you discover this way should be considered in flux until the official documentation is ready.

Monday Aug 11, 2008

How the Shindig REST API works (Java version)

NOTE: this is out-of-date now. The latest version of the diagram and synposis below is here: Shindig/Java's latest REST/RPC implementation.

Project SocialSite uses Apache Shindig (incubating) to implement the OpenSocial REST and JavaScript APIs. We've also got a set of REST and JavaScript APIs that go beyond what is offered in OpenSocial. We're currently in the process of transitioning our APIs from a proof-of-concept implementation to one that uses the new Shindig REST API infrastructure and complies with OpenSocial's rules for extensions. To do this the team needs to come up to speed quickly on how the Shindig REST API works, so here's a quick run through based on knowledge I've gained so far.

You probably won't find this interesting unless you're on the Project SocialSite or Apache Shindig team, or you are working on integrating Shindig into your Java-based Social Networking application. Feedback is welcome; please let me know what I've got wrong about Shindig.

Shindig REST API internals

I'm going to use a diagram of the key Shindig classes and the request processing story to illustrate the inner workings of the REST API implementation. Here's the diagram.

diagram of key Shindig REST API classes

And here's the request processing walk-through.

1... A request enters Shindig via the DataServiceServlet, which has a map of DataRequestHandlers (which it got from the HandlerProvider) keyed by the route that each handles. It's also got a pair of bean converters, which will come into play later when we need to convert outgoing POJOs to XML or JSON representation.

2... The Servlet creates a RequestItem, which parses the request for easy access later. The request item also has a pair of converters which can be used to convert incoming XML or JSON data into Java POJOs.

3... The Servlet calls the appropriate handlers. If the request is a single request, then the Servlet looks up a DataRequestHandler based on the request's "route" (i.e. the first segment of URL's pathinfo). The Servlet calls the selected handler, hands it a request item. If the request is a batch request then the Servlet does the same as above, but in a loop collecting request items.

4... One of Shindig's three request handlers then handles the request and returns a ResponseItem or (plural) items containing the Plain Old Java Objects (POJOs) to be returned to the called. This is the point where incoming XML or JSON data is de-serialized to POJO form by a call to requestItem.getPostData(). Shinding provides three DataRequestHandlers:

  • PersonHandler: returns Person objects with detailed profile information
  • ActivtyHandler: returns Activities of people or group, allows activity creation
  • AppDataHandler: returns Gadget data, allows Gadets to store data

NOTE: If want to add your own REST APIs to Shindig, you can do it by hooking in your own handlers. Use Guice dependency injection to hook in your own custom HandlerProvier, one that returns your own custom handlers.

5... The Shindig handlers call the Shindig Service Provider (SPI), which is defined by a set of interfaces with methods that return ResponseItems. There is a set of model objects, aka POJOS, shown in green that represent the different data types that can be returned by the REST APIs. The service implementations return these POJO objects and expect the Shindig infrastructure to automatically map POJO to either JSON or XML as appropriate.

  • PersonService: returns Person objects with detailed profile information
  • ActivtyService: returns Activities of people or group, allows activity creation
  • AppDataService: returns Gadget data, allows Gadgets to store data

NOTE: the SPI is where you hook in to Shindig if you want to expose your application's Social Graph data via the standard OpenSocial REST API. You implement these interfaces with code that calls your back-end to create, retrieve update and delete data. And you hook your implementation via Guice.

6... The handler returns a ResponseItem, which wraps one or a collection of POJOs. The Servlet may then write that response out or, in the batch case, continue to call handlers and collect more ResponseItems.

7...Servlet converts/serializes and returns ResponseItems. Once the handler, or handlers in the batch case, returns the response item(s), the Servlet calls the appropriate converter to serialize the item(s) to either JSON or XML format depending on what was specified in the 'format' request parameter.

That's that...

I left out a fair number of details, but the above should be enough to help you get started in your own explorations of the code. I'll follow up on the Project SocialSite dev list with some specific step-by-step instructions for moving our old services to the new model.


Follow this blog for news and notes about Social Networking, Social Software, trends and information about Sun's new Project SocialSite.


« April 2017