REST vs JS API feature parity

[Chris Chabot]

I'm not far along yet to be able to have a complete insight into the
situation, but the RESTful spec example to 'create a friend
relationship' did make me wonder:

Are we aiming for feature parity between the Open Social Javascript
API and the RESTful API ?

Right now (as far as I'm aware) you can't 'create a friend
relationship' though the JS API, however the RESTful API does define
this; Is this an oversight in regards to the JS API, overshooting our
goal for the RESTful API, or intended?

It would seem to me that the REST & JS API's -should- have feature
parity, ie a different protocol for the exact same services; Otherwise
it might quickly become confusing why certain features are not
available in one or the other?

Thoughts?

-- Chris

[Ropu]

+1 for parity...

this way app can be "ported" from gadgets, to mobile, to desktop without the need of reducing functionality.

my 2 cents.

ropu

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

[Kevin Brown]

I'm supportive of parity -- anything else is confusing. There will certainly be some things that are different, but the ability to manipulate data needs to be the same in both.

[Chris Chabot]

Ok i think we can assume consensus on this topic (I don't see why there wouldn't be).

How should we go about resolving this conflict (being able to add friends through fields such as "id", "name", "email", or a mix off- through the RESTful API). Remove it from the REST API spec or add it to the JS spec?

Plus should we leave it for 0.9 or is this something that is a part of 'implementing the RESTful API' and have consistency in 0.8 already?

My proposal is to remove it from the current REST API spec, and talk about it again when we're working on 0.9.

-- Chris 

[David Primmer]

-1 for forced parity. 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. The containers should be free to offer
different capabilities via the REST api since you could imagine an
administrative or privileged use of the sns, that may need to
manipulate different resources. Imagine interaction between containers
or where one hosting site manages many containers.

davep

[Chris Chabot]

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

Some containers might want to support adding friends through gadgets,
some might want to do that through the RESTful API, isn't it up to the
ACL structure underneath to define what is allowed when?

-- Chris

[Kevin Marks]

One thing that is different is that People/Friends has been read-only for JS, but RESTful defines People, Data and Activites as read/write naturally. There is obvious value in making People writable in some kinds of  container, but it makes sense for containers to be abel to make some services  read-only (in the same way as different containers have different constarints on Data quotas and activitiy readback).

A key distinction is that in the JS API, Request* calls (like requestShareApp or requestPermission) enable containers to ask users  for confirmation, whereas this isn't possible for a RESTful equivalent, unless the container queues them for future user interaction. A requestMakeFriend() call would presumably be the equivalent here.

I can certainly envision an Application wanting to update parts of a users profile - a music playing app updating favorite songs, a book app updating favorite books etc, and particularly a geographic app updating Location.

[Kevin Brown]

On Thu, Jul 17, 2008 at 10:37 AM, Kevin Marks <kevin...@google.com> wrote:

One thing that is different is that People/Friends has been read-only for JS, but RESTful defines People, Data and Activites as read/write naturally. There is obvious value in making People writable in some kinds of  container, but it makes sense for containers to be abel to make some services  read-only (in the same way as different containers have different constarints on Data quotas and activitiy readback).

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.
 

[Louis Ryan]

I think the issue here is that if the RESTful API implicitly defines CRUD operations on all these types then the semantics of each of those operations needs to be documented or at least stated that they are not defined. Its not clear what HTTP DELETE /person/@me/@self is supposed to do so containers are likely to diverge without guidance.

Other non-Opensocial specd examples

DELETE /activity/<some user other than me>/activity id  (deleting someone elses activity)
POST /person/<some user other than me>/@self  (updating someone elses profile data)

On Thu, Jul 17, 2008 at 10:37 AM, Kevin Marks <kevin...@google.com> wrote:

[John Panzer]

The RESTful API has to be at least a superset of the JS API, for certain.

Should the RESTful API be a proper superset?  Note that the JS API is intended for use by gadgets in a fairly restricted environment; the RESTful API is also intended for use in situations where you have more (policy level) capabilities, e.g., a business partner's services. 

John Panzer (http://abstractioneer.org)