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.

About

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

Search

Archives
« April 2014
SunMonTueWedThuFriSat
  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
   
       
Today