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.



You have created a very good pictorial layout, but I think Instead of DataServiceServelet it should be RestAPIServelet or RestServelet.

- Ram Sharma
Impetus Infotech (India) Pvt Ltd, Indore

Posted by Ram Sharma on August 11, 2008 at 10:27 PM EDT #

Hi Dave

its really good diagram of Java Shindig and i think there is not much difference between Java and PHP shindig
Dave i am working with PHP Shindig and may be that name of few files are quite different like PeopleHandler in php is PersonHandler
But few ideas from my side
1. there is no file such as personservice and personhandler , its PeopleServive and PeopleHandler
2. There is new service called as MessageService and to handle it , there is MessageHandler
3. There is JsonDbOpensocialService for Implementation of supported services backed by a JSON DB



Posted by Anand on August 11, 2008 at 11:48 PM EDT #

Ram, I just checked and in the latest Shindig the Servlet is named DataServiceServlet. It was named differently back when there was an Abdera implementation.

Anand, nice to know that the PHP design is so similar to the Java one. Sounds like the PHP version is a little ahead, because there's no MessageService or Handler in in the Java code yet.

- Dave

Posted by Dave Johnson on August 13, 2008 at 03:28 PM EDT #

[Trackback] Mac に Apache Shindig をインストールしたので、ログをメモ。 Java version up 多分これはしなくても大丈夫だけど、Java の version が 1.5 ...

Posted by 京の路 on May 10, 2009 at 11:27 PM EDT #

Post a Comment:
  • HTML Syntax: NOT allowed

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


« July 2016