[OS3] Revisiting the RPC API Question

[James M Snell]

At the face to face, I raised the question about whether or not we can
deprecate the RPC Protocol option. It was decided then that it should
stay. After going through a heck of a lot of edits, I wanted to reopen
the question.

Quick backgrounder... right now, OpenSocial defines two distinct
protocol options... REST and RPC. The RPC protocol is primarily only
used by the JavaScript API currently. Developers don't really use the
RPC protocol directly; rather, they right their applications to the
gadget.io.makeRequest or osapi.* apis which use the RPC protocol under
the covers.

--------------------------------
| APPLICATION |
--------------------------------
| |
| |
-------------- --------------
| REST API | | GADGET API |
-------------- --------------
| |
| --------------
| | RPC API |
| --------------
| |
| |
-----------------
| Container |
-----------------

Hopefully this ascii art comes out properly in the wash here, but this
gives the breakdown that I've been able to see.

Given that what we want to advocate the most is for developers to
write to the JavaScript or REST APIs, I want to strongly recommend
that we deprecate the RPC protocol option in the standard ... but
leave it open for implementors to continue using the RPC protocol if
they so desire as an implementation detail. This means that Shindig
wouldn't have to change it's implementation of the javascript apis but
there's one less thing we have to worry about standardizing. Things
would be the same on the JavaScript API level. All the standard
documents would specify is the contract at the JavaScript API level.

The end result is a much simplified standard overall...

- James

[Craig McClanahan]

I totally agree with the overall sentiment here -- one standardized API is infinitely better than two.  However, I think we need to be prepared to deal with the one significant functional difference (batch requests) to bring REST up to functional parity.

We've got at least one proposal for how to do that.  I'd like to see us at least look at some of the interesting cross-request symbolic references that things like the Facebook Graph API let you do.  But, at the end of the day, a single REST API is definitely the way to go.

Craig

[James M Snell]

Well, that begs the question: are developers utilizing batch requests
at the HTTP level or the JavaScript API level. I have no problem
leaving the notion of batch requests in the JavaScript API, and with
the approach I outlined, there would be zero problem with shindig
continuing to use the RPC protocol under the covers of the javascript
api -- including the batch request portions. We would simply mark it
up as an implementation detail... other implementations might choose
to implement the batch request stuff some other way.

> --
> 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.

[Henry Saputra]

I think its ok to just expose REST APIs as the only server side
protocol for OpenSocial but we need to close these gaps:
1. Move the RPC response format specs
(http://opensocial-resources.googlecode.com/svn/spec/trunk/Core-API-Server.xml#RPC-Response)
to core gadget API as format for the OSAPI calls. The reason is
because REST and JSON-RPC currently has
2. Update and simplify OpenSocial REST APIs to closely follow RESTful
web services principles such as HATEOAS and metadata service.

I would like to have the deprecation of JSON-RPC in 3.0 is accompanies
by addition of these changes into either 2.5.0 or 3.0.0

- Henry

[James M Snell]

On Tue, Apr 24, 2012 at 10:24 AM, Henry Saputra <henry....@gmail.com> wrote:
> I think its ok to just expose REST APIs as the only server side
> protocol for OpenSocial but we need to close these gaps:
> 1. Move the RPC response format specs
> (http://opensocial-resources.googlecode.com/svn/spec/trunk/Core-API-Server.xml#RPC-Response)
>  to core gadget API as format for the OSAPI calls. The reason is
> because REST and JSON-RPC currently has

Agreed. The data structures used within the JavaScript API need to be
properly defined.

> 2. Update and simplify OpenSocial REST APIs to closely follow RESTful
> web services principles such as HATEOAS and metadata service.
>

Also agreed. Better linking, better metadata should go in. I think
those are definitely doable for the 3.0 timeframe. And yes, I was
thinking of the 3.0 timeframe for deprecation of the JSON-RPC stuff. I
would work it in to the rewritten drafts I have been working on.

[Mark W.]

I believe the way the spec is written is that REST and RPC are optional. Either way, we've got two endpoints we need to expose. This might be OK, given, as you said, the RPC one is really the implementation behind the gadget server. If the proposal is to take the RPC and make it an implementation detail, that's fine. The only concern I have is that by keeping it in the open keeps us honest.

Ideally, it would be great if we could have just one endpoint, but not sure that's likely to happen. 

On Tuesday, April 24, 2012 12:37:23 AM UTC-4, James M Snell wrote:

Well, that begs the question: are developers utilizing batch requests
at the HTTP level or the JavaScript API level. I have no problem
leaving the notion of batch requests in the JavaScript API, and with
the approach I outlined, there would be zero problem with shindig
continuing to use the RPC protocol under the covers of the javascript
api -- including the batch request portions. We would simply mark it
up as an implementation detail... other implementations might choose
to implement the batch request stuff some other way.

On Mon, Apr 23, 2012 at 6:10 PM, Craig McClanahan <crai...@gmail.com> wrote:
> I totally agree with the overall sentiment here -- one standardized API is
> infinitely better than two.  However, I think we need to be prepared to deal
> with the one significant functional difference (batch requests) to bring
> REST up to functional parity.
>
> We've got at least one proposal for how to do that.  I'd like to see us at
> least look at some of the interesting cross-request symbolic references that
> things like the Facebook Graph API let you do.  But, at the end of the day,
> a single REST API is definitely the way to go.
>
> Craig
>
> --
> 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-and-gadgets-spec@googlegroups.com.

> To unsubscribe from this group, send email to

> opensocial-and-gadgets-spec+unsub...@googlegroups.com.

[Matt F.]

So long as we have a complete set of compatibility tests for the JavaScript APIs and REST endpoints, do we care about the RPC being in the open?

[Mark W.]

I think as long we have complete coverage for REST, we could position RPC as an implementation detail.

More specifically, we should be positioning REST as THE way you do server to server integration. I agree with James, that ideally, the javascript APIs eat as much of our dog food as possible, i.e. use the REST APIs. I think batch and the file stuff is what's more difficult.