RESTful spec update; lots of updates

[John Panzer]

All,

I've been working to incorporate the feedback on the RESTful spec and solve some of the nagging problems.  While the latest draft isn't perfect, I think it's gotten to a good 80% point:

http://docs.google.com/View?docid=dc43mmng_2g6k9qzfb

The diffs between the prior spec and this one are [ here (link) ].  (There are a lot of diffs scattered all over, sorry about that, future diffs should be much more focused.)

The biggest changes:

• References fields defined for 0.7 JS API
• Specifies how to handle enum type fields
• Fixes XML namespaces for elements inside <content>
• Adds specification for user-relative groups (so you can get a list of groups, basically)
• Adds a section on request context, requestor, authentication and authorization
• Adding a generalized discovery mechanism in section 6; this is the biggest addition, please take a look!! 
  
• Documented more precisely how to construct the various URLs
  
• Added a skeleton Security Considerations section
• Updating Batching to use application/http (cleans things up nicely)
• Added user to user messaging as optional feature (spec taken from earlier thread on this list)

The biggest expansion is the URL and feature discovery mechanism in section 6.  I attempted to write up simpler/smaller/more constrained ways to accomplish these two things:  Let containers tell clients where to find their services and, for optional services, which ones they support.  Everything I tried seemed more ad hoc and nearly as complex as just adopting XRDS-Simple and URI Templates, while being less complete.  So please take a look!

-John

[David Primmer]

section 5. Request Authentication and Authorization Context

There are two requirements that I'd like explained and possibly changed.

1 "MUST be an OAuth 1.0 Service Provider"

2 Containers MUST also support the Consumer Request OAuth extension,
aka the "two legged" scenario
(http://oauth.googlecode.com/svn/spec/ext/consumer_request/1.0/drafts/1/spec.html)

In both of these cases you say "Containers MUST" but is this the spec
for the API server or the container as a whole? Would it be possible
to make the API server not be an Full OAuth SP and simply have it
defer to another one. Or, only support Consumer Request OAuth and not
the full SP implementation that assumes an interactive user?

Is it possible to have #2 required for 0.8 and #1 in 0.9? A brief chat
with Brian Eaton today led us to think that #2 is relatively easy,
whereas #1 involves much more work, has more direct impact on
usability at the SN, and doesn't have a clear use case at this moment.
Maybe someone could present the case where interactive 3-legged OAuth
would be happening more often than the other two forms of auth: Gadget
Token and 2-legged OAuth.

thanks.

davep

[Gary Helmling]

I would like to propose some revisions to the Groups portions of the
RESTful spec, in order to allow for future expansion of group
information.

In general, the current restriction that groups be person (owner)
dependent may work well for groups as named person
collections/relationships between users, but severely limits future
expansion of a group role within OpenSocial. In my case, groups are a
distinct top-level entity and need a unique identifier themselves. A
group may have one person "owner" (organizer) at one point in time,
but that owner/organizer can change over time, which should not
necessitate a new ID.

I believe that with some minor changes, the current use case of groups
as user-dependent named collections can be accommodated, while still
allowing room for a future expansion of group data and functionality.

To that end I would propose revising these group sections:

2.2 A Group Example
Groups are collections of people with extended attributes. The
RESTful API supports querying for the available groups for a given
user. The groups are returned as a collection; each group has a
display name, a container-globally-unique group identifier (which MAY
be implemented relative to a container-globally-unique person
identifier for groups owned by that user) , and a URL link.

application/json representation of a group:

{
"id" : "example.org:34KJDCSKJN2HHF0DW20394:friends",
"title" : "Peeps",
"link" : {rel : "alternate", "href" :
"http://api.example.org/people/example.org:34KJDCSKJN2HHF0DW20394/@friends"
}
}

...

7.2 Groups (http://ns.opensocial.org/groups/0.8)
ggid : Container-globally-unique group identifier; MAY be defined
relative to a container-globally-unique user identifier for user owned
groups.

Groups URI examples:

/groups/{ggid} -- Group data for this group identifier

A collection of groups associated with a user could still be retrieved
through a request on the Groups URI with query parameters:

GET /groups/?uid={guid}

I realize, however, that this has further impact into both the /person
and /activities sections of the API as well, and presents a general
impedance mismatch with the {guid}/{groupid} path convention used in
both of these. But I wanted to get some feedback before proceeding
further.

So what's the consensus? Is broadening the group representation like
this useful or out of scope for the current RESTful API?

Gary H.

[John Panzer]

On Wed, May 7, 2008 at 1:54 PM, David Primmer <david....@gmail.com> wrote:

section 5. Request Authentication and Authorization Context

There are two requirements that I'd like explained and possibly changed.

1 "MUST be an OAuth 1.0 Service Provider"

2 Containers MUST also support the Consumer Request OAuth extension,
aka the "two legged" scenario
(http://oauth.googlecode.com/svn/spec/ext/consumer_request/1.0/drafts/1/spec.html)

In both of these cases you say "Containers MUST" but is this the spec
for the API server or the container as a whole?

This spec is for the API service(s) run by the container.  Feedback on how to clarify this is appreciated (I didn't want to say "API server" since in the default Shindig case, it's all one physical server.)  OAuth involves two things, the OAuth-specific endpoints for getting tokens, and a bit of auth[nz] context on each protected resource call.  It's quite reasonable for a container's API to point at a separate OAuth service for doing the token dance stuff. 
 

Would it be possible
to make the API server not be an Full OAuth SP and simply have it
defer to another one. Or, only support Consumer Request OAuth and not
the full SP implementation that assumes an interactive user?

For the first question, it can certainly outsource the token dance stuff, but it still has to be able to do the authnz request context validation and challenges itself (since this is part of the HTTP request stream it's handling). 

The last question is an important one:  Should we allow containers's API components to only support Consumer Request OAuth, with no way to fully support an interactive web page method for getting an oauth token?  I'd like to keep things flexible and simple and just say OAuth 1.0 + Consumer Request.  The ability to send a user to a web page for them to grant consent instead of having to trust a third party is the only difference, and that's a pretty low bar for a container to meet.  It also lets clients have a stable landscape to build on -- they can decide if their use cases are best served with direct user interactions or with some kind of federation agreement, without having to come up with different solutions for each container they develop for.

Note that if a container really, really doesn't want to support direct user authorization, it can always restrict the set of registered direct-user-authz Consumers to be empty.  But libraries and reference implementations MUST support a non-empty set to support everyone else who wants to allow maximum interoperability.  I know this is kind of tortured logic.

 

Is it possible to have #2 required for 0.8 and #1 in 0.9? A brief chat
with Brian Eaton today led us to think that #2 is relatively easy,
whereas #1 involves much more work, has more direct impact on
usability at the SN, and doesn't have a clear use case at this moment.
Maybe someone could present the case where interactive 3-legged OAuth
would be happening more often than the other two forms of auth: Gadget
Token and 2-legged OAuth.

Hmm, #1 is just standard OAuth, and there's a lot of libraries already out there to support it.  The UI is pretty trivial.  The user experience is not as good, but better than nothing, which is what the long tail of applications get if you have to wait for lawyers to negotiate federation agreements for every integration...

Maybe Brian can chime in?

The use case I'm thinking of here is an independent developer who wants add value to a user's social network data and doesn't want to ask users for their passwords.  For example, a book club web site that adds "Now reading..." activities to your activity stream.  The user experience is pretty much the same as the existing Flickr, OpenAIM, or AuthSub web confirmation pages, which are usable.

 

[Changshin Lee]

I'd like to point out two issues:

1. Which operation is allowed for each URI pattern

The current spec provides URI examples, but I think each possible URI pattern should be defined and have a set of allowed operations. For instance, 

CR /activities/{guid}/@self

R /activities/{guid}/@friends

RUD /activities/{guid}/@self/{aid}

where CRUD means POST GET PUT DELETE.

2. Application ID

appid is introduced in section 7.4, but OpenSocial 0.7 defines that appdata is user-scope, so there's no such concept. Is app-scope of appdata introduced as well in OpenSocial 0.8?

Thanks,

ias

2008. 05. 07, 오전 9:40, John Panzer 작성:

[Brian Eaton]

On Wed, May 7, 2008 at 2:13 PM, John Panzer <jpa...@google.com> wrote:
> Hmm, #1 is just standard OAuth, and there's a lot of libraries already out
> there to support it. The UI is pretty trivial. The user experience is not
> as good, but better than nothing, which is what the long tail of
> applications get if you have to wait for lawyers to negotiate federation
> agreements for every integration...

It's not trivial to implement an OAuth service provider. The crypto
is easy, the hard parts are:

- registering consumers
- deciding on appropriate access levels and resources for OAuth APIs
- identifying and reacting to abuse

Those aren't problems that can be solved by libraries. The second
item, spec'ing out what access rights an OAuth consumer should have,
seems to be something that will have to be standardized in order to be
useful.

(For the consumer request flow, it seems reasonable to state that the
server-to-server API provides the same functionality and access levels
that the gadget-to-server flow provides, because the gadget and the
server are just two sides of the same coin. Adding a third party to
the mix doesn't fit into the analogy: what access rights should the
third-party be able to request, and what is out of bounds?)

> The use case I'm thinking of here is an independent developer who wants add
> value to a user's social network data and doesn't want to ask users for
> their passwords. For example, a book club web site that adds "Now
> reading..." activities to your activity stream.

Good use case. A bunch of bullet points along these lines would be
very useful in guiding development.

[Julian Bond]

John Panzer <jpa...@google.com> Wed, 7 May 2008 14:13:02

>The use case I'm thinking of here is an independent developer who wants
>add value to a user's social network data and doesn't want to ask users
>for their passwords.  For example, a book club web site that adds "Now
>reading..." activities to your activity stream.  The user experience is
>pretty much the same as the existing Flickr, OpenAIM, or AuthSub web
>confirmation pages, which are usable.

I think the spec should allow for non-authenticated access of data.
Probably read only and probably because that data is already public
html. In which case the requirement to support oAuth would become moot.

--
Julian Bond E&MSN: julian_bond at voidstar.com M: +44 (0)77 5907 2173
Webmaster: http://www.ecademy.com/ T: +44 (0)192 0412 433
Personal WebLog: http://www.voidstar.com/ skype:julian.bond?chat
Get _Sirius_ in 2008

[John Panzer]

2008/5/7 Changshin Lee <iasa...@gmail.com>:

I'd like to point out two issues:

1. Which operation is allowed for each URI pattern

The current spec provides URI examples, but I think each possible URI pattern should be defined and have a set of allowed operations. For instance, 

CR /activities/{guid}/@self

R /activities/{guid}/@friends

RUD /activities/{guid}/@self/{aid}

where CRUD means POST GET PUT DELETE.

 

In general the full set of GET PUT DELETE and POST is available, at least potentially, depending on security context.  I added some wording to make this a bit more clear and note that containers can use a standard Allow: header to list the allowed methods for a given specific URI.
 

2. Application ID

appid is introduced in section 7.4, but OpenSocial 0.7 defines that appdata is user-scope, so there's no such concept. Is app-scope of appdata introduced as well in OpenSocial 0.8?

Actually appdata is always per-user-per-app; 0.7 JS just always makes the app part implicit. (Apps are not allowed to see or know about other apps' data in the JS API; the same is probably true of apps in the RESTful API, though the protocol allows for future expansion for things like 'friendly' apps and 'superuser' app-ids that have broader capabilities).
 

[John Panzer]

On Wed, May 7, 2008 at 10:31 PM, Brian Eaton <bea...@google.com> wrote:

On Wed, May 7, 2008 at 2:13 PM, John Panzer <jpa...@google.com> wrote:
> Hmm, #1 is just standard OAuth, and there's a lot of libraries already out
> there to support it.  The UI is pretty trivial.  The user experience is not
> as good, but better than nothing, which is what the long tail of
> applications get if you have to wait for lawyers to negotiate federation
> agreements for every integration...

It's not trivial to implement an OAuth service provider.  The crypto
is easy, the hard parts are:

- registering consumers
- deciding on appropriate access levels and resources for OAuth APIs
- identifying and reacting to abuse

Agreed on all points, but I don't think this is particularly different between standard OAuth and Consumer Request ("two legged") OAuth.
 

Those aren't problems that can be solved by libraries.  The second
item, spec'ing out what access rights an OAuth consumer should have,
seems to be something that will have to be standardized in order to be
useful.

(For the consumer request flow, it seems reasonable to state that the
server-to-server API provides the same functionality and access levels
that the gadget-to-server flow provides, because the gadget and the
server are just two sides of the same coin.

For clients which are registered as gadgets, this is reasonable.  The consumer request flow can also be used by clients that aren't gadgets and there isn't a standard way for such clients to register themselves; that's up to each container right now, though auto-registration is something we should push for -- that spec is languishing, maybe we can push it forward at IIW next week.
 

 Adding a third party to
the mix doesn't fit into the analogy: what access rights should the
third-party be able to request, and what is out of bounds?)

How is this different between consumer-only and consumer-plus-user?  Either way you have to decide how far to trust the consumer.  In the case of consumer-plus-user, you can make this decision actually a bit more easily, because you can double check with the user to see if they're okay with the authorization.
 

[John Panzer]

All,

Another update on the RESTful spec, and this is the one going out for more public review (barring unexpected last minute revisions).  The diffs from the previous rev of May 6 are [ here (link) ], and the latest rev is as always at:

http://docs.google.com/View?docid=dc43mmng_2g6k9qzfb

This rev has a lot of nit picky changes and expansions of text.  It also moved some things around to try to present the data in a better order, so it looks like there are a lot of changes but a lot of them are just migrations.  The section numbers did change (last time, I promise...)

John