[0.8.1] RESTful vs Javascript feature parity

[Chris Chabot]

This topic was raised by the implied ability to be able to add friends
through the RESTful API, while no such functionality exists in the
Javascript API.

One point that was made is that the RESTful API might be used by
trusted parties of the container to perform various actions which
gadgets are not allowed to do, while others pointed out that having
the same API available in JavaScript means 'first party gadgets' would
be able to be much more powerful and allow for the same kind of
functionality there without the need for container specific extensions.

So should the OpenSocial RESTful and Javascript API's have feature
parity and 'add friend(s)' be added to the JS API? (and there by
setting a trend for future developments in this area)

This topic does not seem to have complete consensus yet, but maybe
that can be reached inside of the voting time-frame.

[Chris Chabot]

The discussion on this topic happened here:
http://groups.google.com/group/opensocial-and-gadgets-spec/browse_thread/thread/2c89a6b509f24ac6?hl=en#

[Cassie]

+1 for as much parity as possible
js vs restful vs json restful are just different formats for the same data

[David Primmer]

-1 for the reason stated in the referenced thread. Is it necessary for
us all to revote in this thread?

davep

[Chris Chabot]

Hi David,

To keep things organized and easily trackable to see if we actually
voted this into 0.8.1 or not, yes it's quite useful to revote and
clarify your positions.

In the thread in which you voiced your objection you mentioned:
"If it were only app developers using both, then
it makes sense to have them be the same. But the audience of the two
interfaces is not the same"

To which there were a couple of reactions, including (for instance) from

Kevin Brown:
"This is already covered by ACLs (the container can simply not support
these
operations). The most likely outcome would be adding these to the JS
API,
not removing them from REST. Not supporting the write ops in the JS
makes it limiting for writing
first-party gadgets, which may have more privileges than third-party."

My:
"Sure, different authentications can give different rights ... however
that doesn't mean they don't have to have the same basic API?"

And Cassie's remark on this thread:

"+1 for as much parity as possible js vs restful vs json restful are
just different formats for the same data"

However you never responded or engaged in further dialog on this
topic. I will always completely encourage people to vote -1 if they
have a strong sentiment towards it, however it does mean your
responsible for defending your -1 and convincing the +1's on why they
missed your perfectly good point on thinking it was a bad idea.
Without that dialog the -1 quickly becomes a 'poison pill' which isn't
healthy for the process in my opinion.

Could you please explain why excerpts i posted above are invalid or
miss out on an important detail, from your point of view? That would
greatly help to move the discussion forward.

Thanks!

-- Chris

[John Hjelmstad]

I like the idea in concept, but I'm unclear on how exactly this translates. A few questions:

1. Is the intended output here a series of JS and RESTful additions that bring each other into parity? If so, this discussion may subsume that for @supportedFields.

2. Or is it instead a forward-looking assertion to be added to a Bylaws (or equivalent) section in the spec discussion group (or spec itself) asserting that A. in some future version we'll meet parity, and B. all ongoing JS or RESTful proposals must have parity?

3. Is there any implied or intended definition of parity? @supportedFields provides an example of what I mean. The proposal there allows querying of such fields on a per-entity basis ie. /people/@supportedFields, while the JS API has opensocial.Environment.supportsField(entity, fieldName), which has notably different calling semantics. This case might simply call for opensocial.Person.supportedFields() and /environment/{field}/@isSupported or similar. I think there are arguments each way.

  On one hand, we might want expressiveness to be completely equivalent on a per-call basis. This would allow every single JS API to map to a RESTful call, leading hopefully to a consistent mapping between the two and making it easier to verify that parity is always reached. But this comes at a significant cost of overhead and ignores the environment in which each API operates.

  The alternate view, probably more sensible, is that each API should be defined according to the most efficient/convenient way in which it is used (the @supportedFields case reflects this), so some sort of mapping must be specified between functionality. What's the form of that mapping? Is it a requirement that every JS API call correspond to at most 1 RESTful API call, or are multiple acceptable? 

  Again, the idea is great. I'd just like to translate this to something concretely actionable for this round.

[David Primmer]

On the ACL argument (that I paraphrase as, implement REST api and JS
api the same and use ACL's to lock down one or the other). I think
this is a fine way to implement the specs, and of course I don't
object to it. But the problem with, as John H said, a new 'bylaw' that
forces the two spec's to stay in lock step, is that you don't let one
of the API's innovate and get out in front of the other when it has
specific needs. I'm not suggesting that the specs be allowed to have a
specific features be done differently or arbitrarily.

What is wrong with the current system that this fixes? You are
proposing a new 'rule' and you need to justify it, not the other way
around.

I agree with John P, that the REST API is a natural superset of the JS
API, and should be allowed, the future, to expand in areas that may
not be useful in a JavaScript context (and vis-versa). John and I have
both given examples in the previous thread and I can't point out all
the potential areas they might differ, that's why I think it should be
unconstrained.

I also think, as John H pointed out, that the proposal is not specific
enough. Does 'parity' mean semantics? Does it mean that the method
signatures are the same? Does it mean we take the PUT and DELETE verbs
out of REST API so that it has parity with the HTTP verbs in JS?

I get the sense that this new rule is to prevent the JS API from being
weakened or ignored, or that forces may lead to some set of developers
being 'shut out' of some functionality in OpenSocial. I don't see that
threat, so I don't see the need for this.

davep

[Chris Chabot]

This should've been a reply on this thread, my apologies for the post mixup:

Hi John, you bring up a very good point actually.

I guess my intend when i wrote the original thread was to reach consensus that we 'intend to aim for feature parity, implemented in a way that makes sense to the situation', which i can see is undefined enough :)

On the other hand i guess is more defined, is my hope that we can prevent a divergence between the functionality of the JS and REST specifications.

It makes more sense to fetch all the supported fields in a single http call through the RESTful interface when your a 3rd party server, but it also makes a lot of sense to inject the supported fields directly into the javascript scope when the gadget is being rendered, and thus saving having to a round trip to retrieve this information.

So i won't suggest reaching a situation where we have abandon what makes sense, however i would suggest having the intend that the both API's should provide the same functionality (but in a way that makes sense for the environment)

[Ropu]

+1 with having the same Functionality, -1 to have a strict mapping in the way these are called/used

as chris said, @supportedFields functionality is more efficient injecting it in JS and with just one call in REST,

but perhaps we can call it /Environment/@SupportedFields, that will return the person and the activity (and, why not, the message types) fields supported is JUST one call.

and in environment we can also have /Environment/@Domain

this way REST will have this functionality too


ropu

--
.-. --- .--. ..-
R o p u

[Evan Gilbert]

Another mixed vote:

+1 on having the same functionality, but think we should vote on supporting specific APIs, for both REST and for JavaScript.

-1 on adding all of the APIs implied by full RESTful support.

The permutations of GET/POST/PUT/DELETE and all of the different URL parameters lead to many edge cases. The JavaScript spec is (mostly) the subset of functionality that people heavlily use, and I don't like building out the general APIs without specific developer use cases we're trying to support. If we do want to support these APIs we should discuss them thoroughly on the list.

Evan