How the Shindig REST API works (Java version)
By davejohnson on Aug 11, 2008
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.
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.
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
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.
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.