Batch Support in RPC Protocol: A quick survey

[James Snell]

Hey all, I'm going through and evaluating the batch support in the RPC
protocol binding and I'm trying to collect information on how and why
and where that's being used. I know parts of the js api rely on it but
I'm trying to evaluate just how critical of a need batch support is.
What are the specific (and real world, actually deployed) reasons for
using it. What is the intended goal for using it. Are people regularly
mixing read and modification operations into a single batch request.
What issues may have come up. etc..

[Henry Saputra]

Its probably better if you create wiki page in OS site to help
managing the info you need.

- Henry

> --
> You received this message because you are subscribed to the Google Groups "OpenSocial and Gadgets Specification Discussion" group.
> To post to this group, send email to opensocial-an...@googlegroups.com.
> To unsubscribe from this group, send email to opensocial-and-gadg...@googlegroups.com.
> For more options, visit this group at http://groups.google.com/group/opensocial-and-gadgets-spec?hl=en.
>

[Mark W.]

I agree with Henry on the wiki page. I will tell you though that we recommend it to our app partners as one of the optimizations you can use. We are, in fact, adding more support for it throughout our APIs.

[James Snell]

I'll get the wiki page set up, but since you say that you're
recommending it and boosting support, my key follow up question would
be why, exactly? Also, what kinds of requests are being batched up
together?

> --
> You received this message because you are subscribed to the Google Groups
> "OpenSocial and Gadgets Specification Discussion" group.

> To view this discussion on the web visit
> https://groups.google.com/d/msg/opensocial-and-gadgets-spec/-/SsFmpP1c8-gJ.

[Mark W.]

Efficiency. There are a couple of scenarios, but the primary one is to retrieve more information about the "stuff" a user has, e.g. blogs, documents, discussions, etc. That's one of the areas we've extended batch, to support jive specific content. (Which I'd love to standardize since we've all got it.) 

So you get a collection of users, batch up the ones you want to know more about and away you go.

Ditto on the user themselves since we typically return only summary objects.

-Mark W.

[Matthew Marum]

I think, with some modifications to the REST API, you could accomplish a lot of use cases in a single request.  For example, a request to a Person URI ought to be able to pull in not just profile data but data from that Person's activity stream, documents, etc. if they are available.

Something like..

GET /social/rest/people/user1?fields=displayName,thumbnailUrl,os:activitystream

would return the display name, thumbnail URL from User1's profile along with data from User1's ActivityStream included inline with this request.

Similarly, a request like

GET /social/rest/people?userId=user1,user2,user3&fields=displayName,thumbnailUrl,os:activitystream

would return all the same data as the above request for users User1, User2, and User3.

You could also specify fields to be lined too..

GET /social/rest/people/user1?fields=displayName,thumbnailUrl,os:activitystream.title

could would be essentially equivalent to

GET /social/rest/people/user1?fields=displayName,thumbnailUrl 

&

GET /social/rest/activitystreams/user1?fields=title

[Li Xu]

+1 to Matt's comments. It would be more effective to leave the lower level server end api to handle the merge of different results.

--
You received this message because you are subscribed to the Google Groups "OpenSocial and Gadgets Specification Discussion" group.

To view this discussion on the web visit https://groups.google.com/d/msg/opensocial-and-gadgets-spec/-/NHnc1sDJfnUJ.

[Mark W.]

Sure....

So while we might be able to modify the rest api to support this, how would this get exposed via JavaScript? Did we just hose up the programming model by forcing a bunch of parameters on the people service? Not sure....

Also remember you can batch up calls to external sites, not just those to the container.

I guess what I'm lacking is the real context behind the question. What is the reason to get rid of batch? Is it b/c we want just REST? What am I missing?

[Matthew Marum]

I agree that the REST model I proposed is a little awkward if we translate it directly to the JavaScript API, maybe it should work differently there.  But I think it's a good direction to take the REST APIs to make them more robust.

That is a good point about external sites.  Batch requests are a convenient way to line up a bunch of HTTP requests that need to be proxied.

Matt

--

You received this message because you are subscribed to the Google Groups "OpenSocial and Gadgets Specification Discussion" group.

To view this discussion on the web visit https://groups.google.com/d/msg/opensocial-and-gadgets-spec/-/rQFJfqP99S0J.

[James Snell]

Hmm.. just so I fully understand.. how does this batching up requests
to external sites thing work? One request to my server results in
n-requests to n-separate other servers? If so, how does the response
data get composed and returned to my browser? Is there a requirement
that all the external requests must return like-structured/formatted
data? Does it only work for GETs? How are individual error conditions
handled? How is authentication handled? None of this is specified
within the Core API specification that defines the basic batching
mechanism so I'm pretty much just left to guessing how it it's
supposed to maybe possibly work.

[Bastian Hofmann]

Hi,

you can create an osapi.BatchRequest with osapi.newBatch() and then
add multiple osapi requests (including osapi.http requests) to this
batch with

batchRequest.add(key, request);

Authorization is set for each HTTP request separately in each request object.

with

batchRequest.execute(callbackFunction)

you then send a single request to the rpc api which executes each
request and returns an associative json with the given request key and
the response object for each request.

It's specified here:
http://opensocial-resources.googlecode.com/svn/spec/2.0.1/Core-Gadget.xml#osapi.BatchRequest

Cheers

Bastian

[Mark W.]

James,

I was going to point you to the same link Bastian did. I think there are a number of things handled that your previous post points out. I'm not in favor of deprecating it. In fact, Facebook has done some very clever batch processing that we might consider looking at down the road.

Enhancing the REST APIs seems a different topic.

[James Snell]

Then separate the rpc protocols and rest protocols into separate distinct pieces. Define a core Rest protocol, then separately define and describe the rpc binding specifically as it relates to the Javascript API.

--

You received this message because you are subscribed to the Google Groups "OpenSocial and Gadgets Specification Discussion" group.

To view this discussion on the web visit https://groups.google.com/d/msg/opensocial-and-gadgets-spec/-/gkgXdf8vHG4J.

[Laurent-Walter Goix]

Hello all,

i do not have a strong opinion on the technical solution to maintain/
update to allow batch processing. However this is surely a topic of
great interest when coming to the mobile world that is under
consideration within OMA spec.

Again, no final decision has been made so far on this topic, also
considering the uncertainty brought by this thread. But surely some
support for optimizing air traffic allowing request batch/merge over a
single http transaction would be appreciated.

walter

On Feb 7, 12:44 am, James Snell <jasn...@gmail.com> wrote:
> Then separate the rpc protocols and rest protocols into separate distinct
> pieces. Define a core Rest protocol, then separately define and describe
> the rpc binding specifically as it relates to the Javascript API.

> On Feb 6, 2012 3:39 PM, "Mark W." <weitzelm.w...@gmail.com> wrote:
>
>
>
>
>
>
>
> > James,
> > I was going to point you to the same link Bastian did. I think there are a
> > number of things handled that your previous post points out. I'm not in
> > favor of deprecating it. In fact, Facebook has done some very clever batch
> > processing that we might consider looking at down the road.
>
> > Enhancing the REST APIs seems a different topic.
>
> > --
> > You received this message because you are subscribed to the Google Groups
> > "OpenSocial and Gadgets Specification Discussion" group.
> > To view this discussion on the web visit

> >https://groups.google.com/d/msg/opensocial-and-gadgets-spec/-/gkgXdf8...
> > .

[James Snell]

The fundamental problem whenever the question of batching requests
comes up (and it's come up in a LOT of places) is the near complete
lack of a CLEAR definition of what is being batched, why exactly is it
needed. In nearly every case I've seen where batching was put on the
table as a possible solution, an exploration of the actual use case
showed that the need for batching disappeared completely through
better data modeling and application design... that is, why develop a
model for batching multiple individual requests into one request when
you can simply make a single request more efficient by changing the
way the data is modeled? So the key question I would have for you is
what exactly does "some support for optimizing air traffic" mean? What
exactly needs to be optimized and how...

[Henry Saputra]

I think the basic or main idea to support batch requests is
possibility to serve up different types of data (eg: person,
activities, spaces) in one single HTTP request.

Unless we have support for "universal object" which support different
data type in OpenSocial specs to allow REST style APIs to get data
with different types of data, we need to support the RPC protocol to
for the data API batch requests.

- Henry

[Mark W.]

James,

It's interesting, because we've seen the opposite--that batching requests actually helps performance. I also think the current batch model is pretty clear that you get a dictionary with the key/value pairs. What use cases have you seen where changing the data model has made batching unnecessary? Could you give a more concrete example?

[James Snell]

Mark,

Given the way things are currently defined in the API's, I have little
doubt that batching helps performance, but that's not really the point
I'm trying to make...

Consider this: http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven#comment-743.

The salient points: "People perceive a need for batch operations
because they don’t understand the scope of resources... [t]he same
resource state can be overlayed by multiple resources, just as an XML
document can be represented as a sequence of bytes or a tree of
individually addressable nodes. Likewise, a single resource can be the
equivalent of a database stored procedure, with the power to abstract
state changes over any number of storage items... If you find yourself
in need of a batch operation, then most likely you just haven’t
defined enough resources."

Let's look at the case you brought up in your earlier message. You
said: "So you get a collection of users, batch up the ones you want to

know more about and away you go."

My question to this is: why do we need a "batch" request?

Consider.. this is what a current RPC batch request currently looks
like in the RPC model..

POST /rpc HTTP/1.1
Host: api.example.org
Authorization: hh5s93j4hdidpola
Content-Type: application/json
[
{
"method" : "people.get",
"id" : "myself",
"params" : {
"userId" : "@me",
"groupId" : "@self"
}
},
{
"method" : "people.get",
"id" : "myfriends",
"params" : {
"userId" : "@me",
"groupId" : "@friends"
}
}
]

The thing that strikes me as very odd about this is.. why isn't it just...

POST /rpc HTTP/1.1
Host: api.example.org
Authorization: hh5s93j4hdidpola
Content-Type: application/json
{
"method" : "people.get",
"id" : "myself",
"params" : {
"userId" : "@me",
"groups": ["@self","@friends"]
}
]
}

Or even better...

GET /people/@me/@self,@friends HTTP/1.1
Host: api.example.org
Authorization: hh5s93j4hdidpola

From everything that I can see, the *ONLY* reason batching is required
here is because of how the people.get operation is currently defined.
With either of the two alternatives I suggest, the requirement for a
batch request completely disappears. The GET option would be WAY more
efficient than the POST /rpc with a batch request option could ever
be. Period.

In your note you also said that another case "is to retrieve more

information about the "stuff" a user has, e.g. blogs, documents,

discussions, etc. " ... to which the natural question is: Well, why
isn't there a single operation that would allow you to retrieve this
information? I'd argue, as Roy suggests in the quote above, the only
reason you'd need to batch requests to get the data you need is
because we have created enough resources. We can take the time now to
define those missing resources, and we can take the time to define
something like the Persistent Query Service and better search and
filter capabilities to completely eliminate the need for batching
requests altogether.

We simply need to define new resources that provide all the information we need.

If you still think batching is an absolute requirement, let's put it
to a test... show me a use case that absolutely requires batch request
capability and if I'm not able to demonstrate that the same case can
be implemented more efficiently without batching, I'll concede on the
point.

- James

> --
> You received this message because you are subscribed to the Google Groups
> "OpenSocial and Gadgets Specification Discussion" group.
> To view this discussion on the web visit

> https://groups.google.com/d/msg/opensocial-and-gadgets-spec/-/-pUQfbGJcTMJ.

[Henry Saputra]

How about request like this:

POST /rpc HTTP/1.1
Host: api.example.org
Authorization: hh5s93j4hdidpola
Content-Type: application/json
[
{
"method" : "people.get",
"id" : "myself",
"params" : {
"userId" : "@me",
"groupId" : "@self"
}
},
{

"method" : "activitystreams.get",
"id" : "mystreams",

"params" : {
"userId" : "@me",
"groupId" : "@self"
}
}

]

One way to use REST is to have a universal object data type so we
could have something like:

GET /universalobject/@me/@self?objecttypes=people:activitystreams&people_userId=@me&people_groupId=@self&activitystreams_userId=@me&activitystreams_groupId=@self

Overloading REST to do this kind of request probably not a good and clean way.

Another way, like Matthew Marum has said, we could piggyback
activitystreams request to the field response of the person. But this
way force developers to be "creative" to find out how to send batch
requests for different data types.

Not sure if either way is the best way to achieve multi data types requests.

- Henry

[James Snell]

So if I'm reading this correctly, it's basically just a call to
retrieve the profile and the activity stream for @me, right?

GET /api/@me/@self,@stream HTTP/1.1
Host: api.example.org
Authorization: hh5s93j4hdidpola

Which can return something as simple as...

{
"@self": {
// the profile
},
"@stream": {
// the stream
}
}

- James

[Henry Saputra]

So we mapped @self to profile and @stream to activity stream?

I assume /api is the root context for the REST APIs or the same level
as /person and /activitystream?

It just feel like sounds like we are trying forcing existing use cases to REST.

I believe REST and JSON-RPC endpoints serve different purpose.
The REST endpoints are primarily used for server to server
communication and JSON-RPC usually used by JavaScript/ OS gadgets
clients.

Currently, the OS REST specs are not super clean and also they arent
100% follow the basic guidelines of RESTful web services (or APIs).
For example, the response format does not have any links that let
client on how to get different resources that could be reached by
another resource.

I propose we clean up the REST protocol for OS for one spec release
and once the implementation catch up with the specs upgrade and we
still believe there is no need for JSON-RPC protocol we could revisit
this removing/ deprecating it.

- Henry

[James Snell]

On Tue, Feb 7, 2012 at 8:38 PM, Henry Saputra <henry....@gmail.com> wrote:
> So we mapped @self to profile and @stream to activity stream?
>
> I assume /api is the root context for the REST APIs or the same level
> as /person and /activitystream?
>
> It just feel like sounds like we are trying forcing existing use cases to REST.

No, I'm trying to say that we can do a heck of a lot better supporting
those use cases than what we currently have by intelligently
refactoring the api.

>
> I believe REST and JSON-RPC endpoints serve different purpose.
> The REST endpoints are primarily used for server to server
> communication and JSON-RPC usually used by JavaScript/ OS gadgets
> clients.

Why can't the javascript/os gadget clients use the REST api?

>
> Currently, the OS REST specs are not super clean and also they arent
> 100% follow the basic guidelines of RESTful web services (or APIs).
> For example, the response format does not have any links that let
> client on how to get different resources that could be reached by
> another resource.
>
> I propose we clean up the REST protocol for OS for one spec release
> and once the implementation catch up with the specs upgrade and we
> still believe there is no need for JSON-RPC protocol we could revisit
> this removing/ deprecating it.
>

If we do a 2.5 spec, I agree, leave it as is technically but clean up
the spec. My proposal for removing the RPC protocol is for 3.0 and
beyond.

[Craig McClanahan]

On Tue, Feb 7, 2012 at 8:21 PM, James Snell <jas...@gmail.com> wrote:

So if I'm reading this correctly, it's basically just a call to
retrieve the profile and the activity stream for @me, right?

 GET /api/@me/@self,@stream HTTP/1.1
 Host: api.example.org
 Authorization: hh5s93j4hdidpola

Which can return something as simple as...

{
 "@self": {
   // the profile
 },
 "@stream": {
   // the stream
 }
}

Or maybe

{

  // the profile

  activity : {

    // the stream

  },

  @friends : [

    // my friends

  ]

}

and use "fields=...,activity,@friends..." to say you want both?

There are still some complications (like, how do I use query parameters or something to filter which activities I want versus which friends I want (perhaps with different pagination criteria for each), when I might also need filtering on some other nested objects.  We would also very much want to provide easy ways for the app developer to "follow the yellow brick road" by doing things like including URLs to get the next or previous page of activities, or the next page or previous page of friends, in some other request.

Also, I can see use cases where you really do want to collect disparate sets of information (i.e. completely independent resources), where it doesn't make sense to define a composite resource, and just want to do them all at once to reduce the network bandwidth effects of doing multiple requests.  It's not easy to imagine this strictly within the OpenSocial spec very much, because there are such a limited number of different data objects, but with richer data models of OpenSocial implementation servers, there will definitely be more places where batch requests  could be useful -- especially in network environments with high latency per request.

It's also interesting to contemplate multiple create/update/delete operations that the client would really like to see performed all-or-nothing.

 

- James

Looking forward to the summit!

Craig McClanahan

[James Snell]

Yes, it is easily possible to imagine much more complex query
scenarios but even those do not really call for the use of batch
requests. On the contrary, I can easy turn the examples you provide
into an argument for the kind of Persistent Query Service I proposed
in a separate note. Such complex query operations are rarely ad hoc,
on the fly queries, but even if they are, there are optimizations and
functionality that a more formalized query service could provide that
go way beyond the existing batch rpc model that exists today. Roy
Fielding's "stored procedure" analogy is rather spot on in this
particular case.

[Mark W.]

I agree with Craig's point: "Also, I can see use cases where you really do want to collect disparate sets of information (i.e. completely independent resources), where it doesn't make sense to define a composite resource, and just want to do them all at once to reduce the network bandwidth effects of doing multiple requests."

This is one of the key use cases for the current batch. 

I also agree with Henry's point, the REST and and RPC endpoints serve two different purposes and I think his idea of keeping the two things distinct for now is a good one. Let's get the REST APIs the way we want them, then we can merge with RPC--if we want.

[James Snell]

This still does not address the fundamental question of why the stuff
that's currently using the RPC-protocol can't just be using the REST
stuff, but I'll leave that one alone for now and suggest, in light of
this, let's split the descriptions of the two protocols into distinct
documents. Doing so will make it significantly easier later on to "get
the REST APIs the way we want them" and make the necessary changes to
reconcile the two later on as necessary.

> --
> You received this message because you are subscribed to the Google Groups
> "OpenSocial and Gadgets Specification Discussion" group.

> To view this discussion on the web visit

> https://groups.google.com/d/msg/opensocial-and-gadgets-spec/-/0CAxFqqfILAJ.

[Mark W.]

+1. Small bites.