semantics of the restful server url templates

[David Primmer <da...@gmail.com>]

We're struggling with these implementation details right now. I'd love
to see what others have decided on.

quick summary of the proposed url system (just for the people api)

/people/{uid}/all            -- Collection of all people connected to user {uid}
/people/{uid}/friends        -- Collection of all friends of user
{uid}; subset of all
/people/{uid}/{groupid}      -- Collection of all people connected to
user {uid} in group {groupid}
/people/{uid}/all/{pid}      -- Individual person record.
/people/{uid}/sel            -- Self Profile record for user {uid}
/groups/{uid}/self           -- Collection of groups owned by the
user, which always contains 'all' and 'friends' and may contain more.
(Details TBD)


We're expressing the friend graph in some of these queries but It's
not clear from the spec how to resolve {uid} and {pid}, especially if
they may actually be in the same underlying person data table. In the
sample file state-basicfriendlist.xml, the user's ID's are simple
firstname.lastname and relations to friends are through this primary
key and the data set is self-referential.

contrary to this simple data set, we should assume that there will be
some hidden primary key in the account/user data we're exposing and
that the public name someone refers to is translated to something else
by the service's backend. For example, your userid may be 'john.doe'
at some social network, but the primary key on your user record in
their database will be some other form of GUID that you never see like
"john.doe.xyz123" in that system.

"/people/{uid}/self"  is the simplest pattern above but even it raises
a lot of questions. It is the profile of the user -- uid in this case
is the user of the application. I'll use gmail as an example system.
"uid" here is a gmail account, john.doe@gmail.com (what does the
actual url string look like?
"http://host.com/social-api/people/john.doe/self" ? ). The profile is
the profile info that the user has recorded for that account. I'm
assuming the 'view' of this data is the full projection and the api
would allow them to edit it.

Under the covers, the john.doe user name or profile name needs to map
to a GUID in the container's auth system. And, the request will come
with an auth an "x-oauth-os-uid" header or parameter that includes a
link to the GUID of the user with right to act as that user. (may be
an admin account that can act on behalf of that user). In this
scenario, it seems that even if we have a GUID for the authorization,
we still need to be able to deterministically look up "john.doe" in
the backend. Or, is it true that {uid} above can be very loose as the
actual identity of the user of the app will come from the auth
context?

And just to dip my toe in the grammar of the urls,
/people/{uid}/all/{pid}, which is an individual person record who is
associated with {uid}. I'd assume that in a situation where the url is
"http://host.com/social-api/people/john.doe/all/john.doe", we'd be
looking up "john.doe" (the one on the left side of the "all") first as
a primary user of the container and then looking in the collection of
contacts for john.doe That could include someone named "john.doe" but
not not a full member of that particular container (the difference
between being a gmail user and that gmail user having a contact who
happens to be named the same as them or have their email address). In
this case, we're not actually going into the friend graph of the local
system but into the private contact storage of the user. (I believe
Plaxo has this sort of distinction). The rules would change if we were
on a closed system where you could only 'friend' someone in the system
that had a uid. In that case the people/john.doe/all/john.doe wold be
illegal. I guess the meaning of these relations isn't clear to me, nor
is how much of this shindig needs to codify.

davep

Re: semantics of the restful server url templates

[David Primmer <da...@gmail.com>]

On Tue, Apr 15, 2008 at 12:08 PM, John Panzer <jp...@google.com> wrote:
> More detailed comments below:
>
>
>  On Mon, Apr 14, 2008 at 10:02 PM, David Primmer <da...@gmail.com>
>  wrote:
>  >
>  > And just to dip my toe in the grammar of the urls,
>  > /people/{uid}/all/{pid}, which is an individual person record who is
>  > associated with {uid}. I'd assume that in a situation where the url is
>  > "http://host.com/social-api/people/john.doe/all/john.doe", we'd be
>  > looking up "john.doe" (the one on the left side of the "all") first as
>  > a primary user of the container and then looking in the collection of
>  > contacts for john.doe That could include someone named "john.doe" but
>  > not not a full member of that particular container (the difference
>  > between being a gmail user and that gmail user having a contact who
>  > happens to be named the same as them or have their email address). In
>  > this case, we're not actually going into the friend graph of the local
>  > system but into the private contact storage of the user. (I believe
>  > Plaxo has this sort of distinction).
>
>  Right.
>
>
>
>  > The rules would change if we were
>  > on a closed system where you could only 'friend' someone in the system
>  > that had a uid. In that case the people/john.doe/all/john.doe wold be
>  > illegal. I guess the meaning of these relations isn't clear to me, nor
>  > is how much of this shindig needs to codify.
>
>  I'm not sure why this would be illegal?
>

Well, if you're allowed to friend yourself on the system, I guess it
would work. It would return the shared profile view of the person who
was accessing it I guess. That view myself as others see me api call
is something else isn't it? or is this it? It's a weird corner case.

The whole {uid} is really a guid thing really cleared up a lot for me.

thanks.

>
>  >
>  >
>  > davep
>  >
>

Re: semantics of the restful server url templates

[John Panzer <jp...@google.com>]

More detailed comments below:

On Mon, Apr 14, 2008 at 10:02 PM, David Primmer <da...@gmail.com>
wrote:

> We're struggling with these implementation details right now. I'd love
> to see what others have decided on.
>
> quick summary of the proposed url system (just for the people api)
>
> /people/{uid}/all            -- Collection of all people connected to user
> {uid}
> /people/{uid}/friends        -- Collection of all friends of user
> {uid}; subset of all
> /people/{uid}/{groupid}      -- Collection of all people connected to
> user {uid} in group {groupid}
> /people/{uid}/all/{pid}      -- Individual person record.
> /people/{uid}/sel            -- Self Profile record for user {uid}
> /groups/{uid}/self           -- Collection of groups owned by the
> user, which always contains 'all' and 'friends' and may contain more.
> (Details TBD)
>
>
> We're expressing the friend graph in some of these queries but It's
> not clear from the spec how to resolve {uid} and {pid}, especially if
> they may actually be in the same underlying person data table. In the
> sample file state-basicfriendlist.xml, the user's ID's are simple
> firstname.lastname and relations to friends are through this primary
> key and the data set is self-referential.


I think we should clarify / change state-basicfriendlist.xml.  My
understanding is that in real life, these IDs are supposed to be universally
unique.  If that's NOT the case, somebody please scream now.  I'd propose
that they be changed to something like example.org:DEADBEEF.


>
>
> contrary to this simple data set, we should assume that there will be
> some hidden primary key in the account/user data we're exposing and
> that the public name someone refers to is translated to something else
> by the service's backend. For example, your userid may be 'john.doe'
> at some social network, but the primary key on your user record in
> their database will be some other form of GUID that you never see like
> "john.doe.xyz123" in that system.
>
> "/people/{uid}/self"  is the simplest pattern above but even it raises
> a lot of questions. It is the profile of the user -- uid in this case
> is the user of the application. I'll use gmail as an example system.
> "uid" here is a gmail account, john.doe@gmail.com (what does the
> actual url string look like?
> "http://host.com/social-api/people/john.doe/self" ? ). The profile is
> the profile info that the user has recorded for that account. I'm
> assuming the 'view' of this data is the full projection and the api
> would allow them to edit it.


Yep.  (In the case of projected views with only a subset of fields, there
will be a <link rel="edit"> pointing at the full representation.)


>
>
> Under the covers, the john.doe user name or profile name needs to map
> to a GUID in the container's auth system. And, the request will come
> with an auth an "x-oauth-os-uid" header or parameter that includes a
> link to the GUID of the user with right to act as that user. (may be
> an admin account that can act on behalf of that user).


With OAuth, there are three possibilities:

1. No x-oauth-os-uid, and no Access Token in oauth_token:  Request is being
made by a third party service, not on behalf of any particular user, and
should be interpreted/rate limited/audited/trusted accordingly.
2. An Access Token in oauth_token: Request is being made by a third party
service on behalf of a user, and the token is proof of the user's
authorization.  The token may have container-specific substructure that lets
you find out what specific user authorized the request, or it may just
contain proof that an appropriate person authorized it.  You may not get a
source {uid} in other words.
3. An x-oauth-os-uid, and no Access Token: Request being made by a third
party service on behalf of a user, and it's telling you the uid of the user
explicitly.  You have to trust the third party service to have consulted
with the user and gotten their implicit (via TOS) or explicit consent, but
the bottom line is that you have some level of trust that lets you accept
the {uid}.

In only one of these situations do you have a requestor {uid} guaranteed to
be available.  In general you don't need it; a container should provide an
implementation of an authorization check interface and the common code just
needs to honor the results.

We _might_ want to allow a special value -- like @me -- for {uid}.  But it
would only be a slight convenience I think.


> In this
> scenario, it seems that even if we have a GUID for the authorization,
> we still need to be able to deterministically look up "john.doe" in
> the backend. Or, is it true that {uid} above can be very loose as the
> actual identity of the user of the app will come from the auth
> context?


{uid} should be deterministically unique.


>
>
> And just to dip my toe in the grammar of the urls,
> /people/{uid}/all/{pid}, which is an individual person record who is
> associated with {uid}. I'd assume that in a situation where the url is
> "http://host.com/social-api/people/john.doe/all/john.doe", we'd be
> looking up "john.doe" (the one on the left side of the "all") first as
> a primary user of the container and then looking in the collection of
> contacts for john.doe That could include someone named "john.doe" but
> not not a full member of that particular container (the difference
> between being a gmail user and that gmail user having a contact who
> happens to be named the same as them or have their email address). In
> this case, we're not actually going into the friend graph of the local
> system but into the private contact storage of the user. (I believe
> Plaxo has this sort of distinction).

Right.


> The rules would change if we were
> on a closed system where you could only 'friend' someone in the system
> that had a uid. In that case the people/john.doe/all/john.doe wold be
> illegal. I guess the meaning of these relations isn't clear to me, nor
> is how much of this shindig needs to codify.

I'm not sure why this would be illegal?


>
>
> davep
>

Re: semantics of the restful server url templates

[John Panzer <jp...@google.com>]

The intent with {uid} is that it's a globally unique identifier.  I know
some of the earlier JS samples used "john.doe" but those weren't serious
IDs, right?  The one I've seen bandied about look like
orkut.com:AF38388DEADBEEF.


The individual {pid}s don't need to be universally unique -- they could be
relative to the {uid}.  Obviously globally unique {pid}s work too.  I think
this could be a container decision.

On Mon, Apr 14, 2008 at 11:40 PM, Kevin Brown <et...@google.com> wrote:

> It sounds to me that some of these things need further clarification in
> the
> spec itself. Shouldn't the url format be well defined for these cases?
>
> On Mon, Apr 14, 2008 at 10:02 PM, David Primmer <da...@gmail.com>
> wrote:
>
> > We're struggling with these implementation details right now. I'd love
> > to see what others have decided on.
> >
> > quick summary of the proposed url system (just for the people api)
> >
> > /people/{uid}/all            -- Collection of all people connected to
> user
> > {uid}
> > /people/{uid}/friends        -- Collection of all friends of user
> > {uid}; subset of all
> > /people/{uid}/{groupid}      -- Collection of all people connected to
> > user {uid} in group {groupid}
> > /people/{uid}/all/{pid}      -- Individual person record.
> > /people/{uid}/sel            -- Self Profile record for user {uid}
> > /groups/{uid}/self           -- Collection of groups owned by the
> > user, which always contains 'all' and 'friends' and may contain more.
> > (Details TBD)
> >
> >
> > We're expressing the friend graph in some of these queries but It's
> > not clear from the spec how to resolve {uid} and {pid}, especially if
> > they may actually be in the same underlying person data table. In the
> > sample file state-basicfriendlist.xml, the user's ID's are simple
> > firstname.lastname and relations to friends are through this primary
> > key and the data set is self-referential.
> >
> > contrary to this simple data set, we should assume that there will be
> > some hidden primary key in the account/user data we're exposing and
> > that the public name someone refers to is translated to something else
> > by the service's backend. For example, your userid may be 'john.doe'
> > at some social network, but the primary key on your user record in
> > their database will be some other form of GUID that you never see like
> > "john.doe.xyz123" in that system.
> >
> > "/people/{uid}/self"  is the simplest pattern above but even it raises
> > a lot of questions. It is the profile of the user -- uid in this case
> > is the user of the application. I'll use gmail as an example system.
> > "uid" here is a gmail account, john.doe@gmail.com (what does the
> > actual url string look like?
> > "http://host.com/social-api/people/john.doe/self" ? ). The profile is
> > the profile info that the user has recorded for that account. I'm
> > assuming the 'view' of this data is the full projection and the api
> > would allow them to edit it.
> >
> > Under the covers, the john.doe user name or profile name needs to map
> > to a GUID in the container's auth system. And, the request will come
> > with an auth an "x-oauth-os-uid" header or parameter that includes a
> > link to the GUID of the user with right to act as that user. (may be
> > an admin account that can act on behalf of that user). In this
> > scenario, it seems that even if we have a GUID for the authorization,
> > we still need to be able to deterministically look up "john.doe" in
> > the backend. Or, is it true that {uid} above can be very loose as the
> > actual identity of the user of the app will come from the auth
> > context?
> >
> > And just to dip my toe in the grammar of the urls,
> > /people/{uid}/all/{pid}, which is an individual person record who is
> > associated with {uid}. I'd assume that in a situation where the url is
> > "http://host.com/social-api/people/john.doe/all/john.doe", we'd be
> > looking up "john.doe" (the one on the left side of the "all") first as
> > a primary user of the container and then looking in the collection of
> > contacts for john.doe That could include someone named "john.doe" but
> > not not a full member of that particular container (the difference
> > between being a gmail user and that gmail user having a contact who
> > happens to be named the same as them or have their email address). In
> > this case, we're not actually going into the friend graph of the local
> > system but into the private contact storage of the user. (I believe
> > Plaxo has this sort of distinction). The rules would change if we were
> > on a closed system where you could only 'friend' someone in the system
> > that had a uid. In that case the people/john.doe/all/john.doe wold be
> > illegal. I guess the meaning of these relations isn't clear to me, nor
> > is how much of this shindig needs to codify.
> >
> > davep
> >
>
>
>
> --
> ~Kevin
>

Re: semantics of the restful server url templates

[Kevin Brown <et...@google.com>]

It sounds to me that some of these things need further clarification in the
spec itself. Shouldn't the url format be well defined for these cases?

On Mon, Apr 14, 2008 at 10:02 PM, David Primmer <da...@gmail.com>
wrote:

> We're struggling with these implementation details right now. I'd love
> to see what others have decided on.
>
> quick summary of the proposed url system (just for the people api)
>
> /people/{uid}/all            -- Collection of all people connected to user
> {uid}
> /people/{uid}/friends        -- Collection of all friends of user
> {uid}; subset of all
> /people/{uid}/{groupid}      -- Collection of all people connected to
> user {uid} in group {groupid}
> /people/{uid}/all/{pid}      -- Individual person record.
> /people/{uid}/sel            -- Self Profile record for user {uid}
> /groups/{uid}/self           -- Collection of groups owned by the
> user, which always contains 'all' and 'friends' and may contain more.
> (Details TBD)
>
>
> We're expressing the friend graph in some of these queries but It's
> not clear from the spec how to resolve {uid} and {pid}, especially if
> they may actually be in the same underlying person data table. In the
> sample file state-basicfriendlist.xml, the user's ID's are simple
> firstname.lastname and relations to friends are through this primary
> key and the data set is self-referential.
>
> contrary to this simple data set, we should assume that there will be
> some hidden primary key in the account/user data we're exposing and
> that the public name someone refers to is translated to something else
> by the service's backend. For example, your userid may be 'john.doe'
> at some social network, but the primary key on your user record in
> their database will be some other form of GUID that you never see like
> "john.doe.xyz123" in that system.
>
> "/people/{uid}/self"  is the simplest pattern above but even it raises
> a lot of questions. It is the profile of the user -- uid in this case
> is the user of the application. I'll use gmail as an example system.
> "uid" here is a gmail account, john.doe@gmail.com (what does the
> actual url string look like?
> "http://host.com/social-api/people/john.doe/self" ? ). The profile is
> the profile info that the user has recorded for that account. I'm
> assuming the 'view' of this data is the full projection and the api
> would allow them to edit it.
>
> Under the covers, the john.doe user name or profile name needs to map
> to a GUID in the container's auth system. And, the request will come
> with an auth an "x-oauth-os-uid" header or parameter that includes a
> link to the GUID of the user with right to act as that user. (may be
> an admin account that can act on behalf of that user). In this
> scenario, it seems that even if we have a GUID for the authorization,
> we still need to be able to deterministically look up "john.doe" in
> the backend. Or, is it true that {uid} above can be very loose as the
> actual identity of the user of the app will come from the auth
> context?
>
> And just to dip my toe in the grammar of the urls,
> /people/{uid}/all/{pid}, which is an individual person record who is
> associated with {uid}. I'd assume that in a situation where the url is
> "http://host.com/social-api/people/john.doe/all/john.doe", we'd be
> looking up "john.doe" (the one on the left side of the "all") first as
> a primary user of the container and then looking in the collection of
> contacts for john.doe That could include someone named "john.doe" but
> not not a full member of that particular container (the difference
> between being a gmail user and that gmail user having a contact who
> happens to be named the same as them or have their email address). In
> this case, we're not actually going into the friend graph of the local
> system but into the private contact storage of the user. (I believe
> Plaxo has this sort of distinction). The rules would change if we were
> on a closed system where you could only 'friend' someone in the system
> that had a uid. In that case the people/john.doe/all/john.doe wold be
> illegal. I guess the meaning of these relations isn't clear to me, nor
> is how much of this shindig needs to codify.
>
> davep
>



-- 
~Kevin

Re: semantics of the restful server url templates

[David Primmer <da...@gmail.com>]

On Tue, Apr 15, 2008 at 4:43 PM, Robert Evans <bo...@google.com> wrote:
> I am trying to think of the URIs as mapping to resources on the web, and
>  trying to read it out loud. Consequently, please see the reading of URIs and
>  some questions/suggestions interspersed below.
>
>  Thanks,
>  Bob

Hey bob,  thanks for asking these questions. This is the stuff that
really needs to be fleshed out. This should probably have originally
been sent to the spec list.... i'm doing that now.

Do you think some of these query like statements are similar to what
the java storage interface needs to look like? Right now there's just
'getPersonData' and 'getPeople'. in Cassie's BasicDataService and
BasicPeopleService. Is there a contribution of this interface coming
to shindig in the future?

>
>  On Mon, Apr 14, 2008 at 10:02 PM, David Primmer <da...@gmail.com>
>  wrote:
>
>
> > We're struggling with these implementation details right now. I'd love
>  > to see what others have decided on.
>  >
>  > quick summary of the proposed url system (just for the people api)
>  >
>  > /people/{uid}/all            -- Collection of all people connected to user
>  > {uid}
>
>
>  Sounds like: "Get people for user, {uid}; all of them."
>
>
>  >
>  > /people/{uid}/friends        -- Collection of all friends of user {uid};
>  > subset of all
>
>
>   Sounds like: "Get people for user, {uid}; only those who are friends."
>
>
>  >
>  > /people/{uid}/{groupid}      -- Collection of all people connected to user
>  > {uid} in group {groupid}
>
>
>  Sounds like: "Get people for user, {uid}; who are also in group_id."
>
>  That one is confusing. Won't this be the same as all people in {group id}? I
>  have only a vague concept of "group" here, so please correct that for me.
>

if groupid is globally unique, then it would probably work. I think
john mentioned that these qualifier variables may not be guids, and
thus would be relative to the {uid} container.
>
>
>  >
>  > /people/{uid}/all/{pid}      -- Individual person record.
>
>
>  Sounds like: "Get people for user, {uid}; All of them. Only with person id,
>  {pid}."
>
>  Why not drop the 'all'? /people/{uid}/{pid}

maybe there's a different projection here? the relationship is implied
less directly than if the resources are just separated by a slash.

>
>  Then it could sound like, "Get people for user, {uid}; with person id,
>  {pid}."
>  Sounds like: "Get people for user, {uid}, with person id {pid}."
>
>
>
>  > /people/{uid}/sel            -- Self Profile record for user {uid}

sorry. typo. this is supposed to be /self
>
>
>  Sounds like, "Get people for user, {uid}; sel."
>
>  Why not drop the 'sel' here, and /people/{uid}/ just refers to that user
>  resource specified by {uid}.

i think what you're saying is basically ok, except that /people/{uid}/
is the collection and not the entry so you'd want /people/{uid}
without the trailing slash to give the profile data for the user. I'll
let john answer as to why he chose these flavors of /self and /all.
They could also be done with opensearch semantics.

>
>
>  > /groups/{uid}/self           -- Collection of groups owned by the
>  > user, which always contains 'all' and 'friends' and may contain more.
>  > (Details TBD)
>  >
>  >
>  Sounds like: "Get groups for user, {uid}; self."
>  Perhaps, predicated on the group definition, it could just be /groups/{uid}
>  which gets all groups that user, {uid} belongs (owns?) to.
>
>  What is group ownership? Is the group any subset of people that a user
>  knows?
>

Re: semantics of the restful server url templates

[Robert Evans <bo...@google.com>]

Things are clearer to me now.

I noticed that there was a case where @all was used, and another where all
was used without the @ sign. Should those both use the @?

Also, AFAIK, the opensocial spec doesn't talk much about public and private
data for a user. That is to say, other than the limited discussion about
appdata read and write access, the spec seems pretty quiet about this issue.
Someone correct that if I am wrong.

On the issue of {pid} and {uid} both being a member of {alluids}. All
implementations I have seen so far respect that. The spec seems quiet on
this notion.

As to groups, thanks for the clarification. It seems like the only place in
the spec that talks about groups is around user_spec for DataRequests, but
it also explicitly says that the only supported groups are VIEWER_FRIENDS
and OWNER_FRIENDS. So, not sure if the spec should include discussion of
managing groups in order to facilitate this RESTful api feature.

Bob

On Wed, Apr 16, 2008 at 6:24 PM, John Panzer <jp...@google.com> wrote:

>
>
> On Wed, Apr 16, 2008 at 6:08 PM, Vasu Nori <vn...@google.com> wrote:
>
>> On Wed, Apr 16, 2008 at 5:51 PM, John Panzer <jp...@google.com> wrote:
>>
>> > Looks good, some comments below:
>> > (Also, + spec list as this is really overlapping with the spec)
>> >
>> > On Wed, Apr 16, 2008 at 2:05 PM, Vasu Nori <vn...@google.com> wrote:
>> >
>> > > Let me summarize People Restful API and the IMPLIED data model behind
>> > > it.
>> > >
>> > > API calls
>> > >
>> > >   - /people/{uid}/all - Collection of all Public profiles for all
>> users
>> > >   connected with uid {uid}
>> > >
>> >
>> > I'm not sure what Public profile means here -- specifically, I think
>> it's
>> > possible for a social network to implement an interface where the
>> records
>> > here are private to the user, or created by the user to describe people
>> he
>> > knows.  They could also be direct representations of a public or
>> > semi-private profile of the target user of course, but I don't think
>> > OpenSocial requires this semantic (right?)
>> >
>> >
>> I made up the word "public".
>> my most fundamental assumption is: A user has a set of attributes to
>> decribe
>> himself/herself. In this set,
>> some attributes are set to be public
>> and some are set to be completely private ("visible" ONLY to self)
>> and some are set to be "visible" only to certain designated groups.
>> does this make sense?
>>
>> if so, the above URL meaning is what I thought was said in the thread
>> earlier by others.
>>
>> I am looking to validate my understanding really.
>
>
> Ah, okay.  But I think this would interact with the access control of the
> requestor.  There's of course a requester (which may be anonymous) in the
> picture here.  Requestor might be different from both {uid} and {pid}.
>
>
>>
>>
>> >
>> > >
>> > >   - /people/{uid}/friends        -- Collection of all Public profiles
>> > >   for all users connected with user {uid} and group = "friends"
>> > >   - /people/{uid}/{groupid}      -- Collection of all people connected
>> > >    to user {uid} in group {groupid}
>> > >    - /people/{uid}/@all/{pid}      -- Public profile, returning ALL
>> > >   attributes of the user {pid} which are visible to ANY of the groups
>> of
>> > > user
>> > >   {uid}
>> > >
>> >
>> > Not quite sure what the above means (the "visible to ANY..." part)
>> >
>> "visible" = the attributes that are returnable in this/a query.
>> maybe bad word..
>>
>> >
>> >
>> >
>> > >
>> > >   - /people/{uid}/@self            -- Return the COMPLETE Profile for
>> > >   user {uid}
>> > >   - /groups/{uid}/@self   -  Return ALL groups for user {uid}
>> > >
>> > >
>> > > Data Model (in the following, Level N+1 is inside Level N object)
>> > >
>> > >   - *Level_1 * Person Object
>> > >   - *Level_2 * uid  String type
>> > >      - *Level_2 * set of all groups for this user
>> > >         - *Level_3  *groupid  (Reserved words: family, friends)
>> > >      - *Level_3 * for each group, contacts
>> > >            - *Level_4 * set of all contacts of in this group
>> > >            (set of Person objects identified by their uid)
>> > >
>> >
>> > Do we want to make each pid also be required to be a uid?  This implies
>> > that pids cannot be relative in any implementation.  (If this is just
>> > talking about the Shindig implementation then ignore this.)
>> >
>>
>> again my assumption is that each "contact" is also a "Person" in the
>> system
>> - the SAME "Person" object defined at Level_1.
>>
>> >
>> >
>> > >
>> > >
>> > >   - *Level_2 * User profile attributes
>> > >
>> > >         - *Level_3 * for each attribute, flag = public/private
>> > >         - *Level_3 * for each attribute, indicate which of the
>> > >         user's groups can view this attribute
>> > >            - *Level_4 *set of groups this attribute belongs to
>> > >
>> > > what do you say?
>> > >
>> > > On Wed, Apr 16, 2008 at 12:07 PM, John Panzer <jp...@google.com>
>> > > wrote:
>> > >
>> > > > On Tue, Apr 15, 2008 at 4:43 PM, Robert Evans <bo...@google.com>
>> > > wrote:
>> > > >
>> > > > > I am trying to think of the URIs as mapping to resources on the
>> web,
>> > > and
>> > > > > trying to read it out loud. Consequently, please see the reading
>> of
>> > > URIs
>> > > > > and
>> > > > > some questions/suggestions interspersed below.
>> > > > >
>> > > > > Thanks,
>> > > > > Bob
>> > > > >
>> > > > > On Mon, Apr 14, 2008 at 10:02 PM, David Primmer <
>> > > david.primmer@gmail.com
>> > > > >
>> > > > > wrote:
>> > > > >
>> > > > > > We're struggling with these implementation details right now.
>> I'd
>> > > love
>> > > > > > to see what others have decided on.
>> > > > > >
>> > > > > > quick summary of the proposed url system (just for the people
>> api)
>> > > > > >
>> > > > > > /people/{uid}/all            -- Collection of all people
>> connected
>> > > to
>> > > > > user
>> > > > > > {uid}
>> > > > >
>> > > > >
>> > > > > Sounds like: "Get people for user, {uid}; all of them."
>> > > >
>> > > >
>> > > > Yes (of course, it really just names the group of all people
>> connected
>> > > to
>> > > > user {uid}, you can do GET/PUT/POST/DELETE on this collection
>> > > depending on
>> > > > what you want to do).
>> > > >
>> > > >
>> > > > >
>> > > > >
>> > > > > >
>> > > > > > /people/{uid}/friends        -- Collection of all friends of
>> user
>> > > > {uid};
>> > > > > > subset of all
>> > > > >
>> > > > >
>> > > > >  Sounds like: "Get people for user, {uid}; only those who are
>> > > friends."
>> > > >
>> > > >
>> > > > Yep.
>> > > >
>> > > >
>> > > > >
>> > > > >
>> > > > > >
>> > > > > > /people/{uid}/{groupid}      -- Collection of all people
>> connected
>> > > to
>> > > > > user
>> > > > > > {uid} in group {groupid}
>> > > > >
>> > > > >
>> > > > > Sounds like: "Get people for user, {uid}; who are also in
>> group_id."
>> > > > >
>> > > > > That one is confusing. Won't this be the same as all people in
>> > > {group
>> > > > id}?
>> > > > > I
>> > > > > have only a vague concept of "group" here, so please correct that
>> > > for
>> > > > me.
>> > > >
>> > > >
>> > > > The concept here is that groups are user-relative too (see below for
>> > > > groups
>> > > > discussion).  My group "family" is much different from your group
>> > > > "family".
>> > > > friends is really exactly this type of group.
>> > > >
>> > > >
>> > > > >
>> > > > >
>> > > > >
>> > > > > >
>> > > > > > /people/{uid}/all/{pid}      -- Individual person record.
>> > > > >
>> > > > >
>> > > > > Sounds like: "Get people for user, {uid}; All of them. Only with
>> > > person
>> > > > > id,
>> > > > > {pid}."
>> > > > >
>> > > > > Why not drop the 'all'? /people/{uid}/{pid}
>> > > >
>> > > >
>> > > > I only put the "all" in there to make the URLs less confusing --
>> > > anything
>> > > > at
>> > > > level 3 is always a person-id, anything at level 2 is always a group
>> > > id.
>> > > > Conceptually you're saying "give me the person record as accessed
>> > > through
>> > > > group 'X'".  Today people records are the same no matter what group
>> > > you're
>> > > > in, but I could imagine wanting to change this (e.g., having a
>> > > > date-added-to-group field) which might vary depending on the
>> context.
>> > > >
>> > > >
>> > > >
>> > > > >
>> > > > >
>> > > > > Then it could sound like, "Get people for user, {uid}; with person
>> > > id,
>> > > > > {pid}."
>> > > > > Sounds like: "Get people for user, {uid}, with person id {pid}."
>> > > > >
>> > > > >
>> > > > > > /people/{uid}/sel            -- Self Profile record for user
>> {uid}
>> > > > >
>> > > > >
>> > > > > Sounds like, "Get people for user, {uid}; sel."
>> > > > >
>> > > > > Why not drop the 'sel' here, and /people/{uid}/ just refers to
>> that
>> > > user
>> > > > > resource specified by {uid}.
>> > > >
>> > > >
>> > > > We could probably drop @self (we added @ signs to make meta-names
>> not
>> > > > conflict with regular names).  Thoughts?
>> > > >
>> > > >
>> > > > >
>> > > > >
>> > > > >
>> > > > > > /groups/{uid}/self           -- Collection of groups owned by
>> the
>> > > > > > user, which always contains 'all' and 'friends' and may contain
>> > > more.
>> > > > > > (Details TBD)
>> > > > > >
>> > > > > >
>> > > > > Sounds like: "Get groups for user, {uid}; self."
>> > > > > Perhaps, predicated on the group definition, it could just be
>> > > > > /groups/{uid}
>> > > > > which gets all groups that user, {uid} belongs (owns?) to.
>> > > >
>> > > >
>> > > > The intended semantics are groups the user owns.  If we drop @self
>> > > then it
>> > > > would just be /groups/{uid}
>> > > >
>> > > >
>> > > > >
>> > > > >
>> > > > > What is group ownership? Is the group any subset of people that a
>> > > user
>> > > > > knows?
>> > > > >
>> > > >
>> > > > A user can in principle set up any number of groups to classify the
>> > > people
>> > > > they know.  They get one special group by default, "friends".  Not
>> > > > everybody
>> > > > they know is necessarily a friend.
>> > > >
>> > > > This is different from groups-you-belong-to in principle, in that
>> you
>> > > can
>> > > > set up a group and stuff me in it without me being aware of it or
>> > > caring.
>> > > > (Again, "friends" is special and has additional semantics -- it's
>> > > double
>> > > > opt
>> > > > in.  Other groups may have special semantics too, but the API
>> doesn't
>> > > > specify those semantics.)
>> > > >
>> > >
>> >
>> >
>> > >
>> >
>>
>
>
> --~--~---------~--~----~------------~-------~--~----~
> 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-unsubscribe@googlegroups.com
> For more options, visit this group at
> http://groups.google.com/group/opensocial-and-gadgets-spec?hl=en
> -~----------~----~----~----~------~----~------~--~---
>
>

Re: semantics of the restful server url templates

[Gary Helmling <gh...@gmail.com>]

On Fri, Apr 18, 2008 at 10:36 AM, John Panzer <jp...@google.com> wrote:
> The idea with the templates is that the pattern is usually:
>
> /{datatype}/{owner-uid}/...
>

Sorry for chiming in so late on this.  I definitely like the
consistency of approach for the APIs.

My concern is mainly around the user-centric nature of this approach
-- though maybe this is out of scope given the focus on single user
interactions from the gadget side?

I'm coming from a very group-centric service, and for accessing the
user group information:

/groups/{uid}/

Seems to limit the future potential for group representations in the
rest api, especially with no unique ID for groups.  I guess ideally, I
would like to see unique IDs for groups, so they can be first class
citizens, and a way of access group information directly, something
like:

/groups/{gid}/ - returns group information with access to member lists
for public groups

with a different way of accessing groups by user:

/groups/all/byuser/{uid}

But of course this doesn't square so well with the /<return
type>/<uid> approach.  Does anyone else see this as an issue, or see
other potential approaches to group information here?


--gh

Re: semantics of the restful server url templates

[John Panzer <jp...@google.com>]

The idea with the templates is that the pattern is usually:

/{datatype}/{owner-uid}/...

where the datatype means that you're dealing with, say, people or
collections of people records.  So for albums I'd suggest:

/albums/{uid}/{photo-album-id}

(Note that a person record can have links off to all the things it owns if
we want to add an ownership graph.  Since many things can potentially be
'owned' by multiple people, a URL path hierarchy would be inappropriate for
determining ownership I think.)

On Fri, Apr 18, 2008 at 10:04 AM, Louis Ryan <lr...@google.com> wrote:

> The URI format used as examples so far seems a little prone to ambiguity?
>
> /people/{uid}/{groupid}
>
> is also a good match for
>
> /people/{uid}/{photo-album-id}
>
> especialy if we intend to allow the use of natural names as identifiers,
> as in..
>
> /people/me/friends
>
> Are we intending to namespace the id's to avoid this issue or just
> namespace by extending the URL pattern
>
> /people/{uid}/groups/{groupid}
>
> Thanks
>
> -Louis
>
>
>
>
> On Thu, Apr 17, 2008 at 6:18 PM, Vasu Nori <vn...@google.com> wrote:
>
> > anyone has a comprehensive set of testdata for "People" to correspond
> > with
> > the datamodel discussed in this thread?
> > just checking..
> >
> > On Wed, Apr 16, 2008 at 6:24 PM, John Panzer <jp...@google.com> wrote:
> >
> > >
> > >
> > > On Wed, Apr 16, 2008 at 6:08 PM, Vasu Nori <vn...@google.com> wrote:
> > >
> > > > On Wed, Apr 16, 2008 at 5:51 PM, John Panzer <jp...@google.com>
> > wrote:
> > > >
> > > > > Looks good, some comments below:
> > > > > (Also, + spec list as this is really overlapping with the spec)
> > > > >
> > > > > On Wed, Apr 16, 2008 at 2:05 PM, Vasu Nori <vn...@google.com>
> > wrote:
> > > > >
> > > > > > Let me summarize People Restful API and the IMPLIED data model
> > > > behind
> > > > > > it.
> > > > > >
> > > > > > API calls
> > > > > >
> > > > > >   - /people/{uid}/all - Collection of all Public profiles for
> > all
> > > > users
> > > > > >   connected with uid {uid}
> > > > > >
> > > > >
> > > > > I'm not sure what Public profile means here -- specifically, I
> > think
> > > > it's
> > > > > possible for a social network to implement an interface where the
> > > > records
> > > > > here are private to the user, or created by the user to describe
> > > > people he
> > > > > knows.  They could also be direct representations of a public or
> > > > > semi-private profile of the target user of course, but I don't
> > think
> > > > > OpenSocial requires this semantic (right?)
> > > > >
> > > > >
> > > > I made up the word "public".
> > > > my most fundamental assumption is: A user has a set of attributes to
> > > > decribe
> > > > himself/herself. In this set,
> > > > some attributes are set to be public
> > > > and some are set to be completely private ("visible" ONLY to self)
> > > > and some are set to be "visible" only to certain designated groups.
> > > > does this make sense?
> > > >
> > > > if so, the above URL meaning is what I thought was said in the
> > thread
> > > > earlier by others.
> > > >
> > > > I am looking to validate my understanding really.
> > >
> > >
> > > Ah, okay.  But I think this would interact with the access control of
> > the
> > > requestor.  There's of course a requester (which may be anonymous) in
> > the
> > > picture here.  Requestor might be different from both {uid} and {pid}.
> > >
> > >
> > > >
> > > >
> > > > >
> > > > > >
> > > > > >   - /people/{uid}/friends        -- Collection of all Public
> > > > profiles
> > > > > >   for all users connected with user {uid} and group = "friends"
> > > > > >   - /people/{uid}/{groupid}      -- Collection of all people
> > > > connected
> > > > > >    to user {uid} in group {groupid}
> > > > > >    - /people/{uid}/@all/{pid}      -- Public profile, returning
> > ALL
> > > > > >   attributes of the user {pid} which are visible to ANY of the
> > > > groups of
> > > > > > user
> > > > > >   {uid}
> > > > > >
> > > > >
> > > > > Not quite sure what the above means (the "visible to ANY..." part)
> > > > >
> > > > "visible" = the attributes that are returnable in this/a query.
> > > > maybe bad word..
> > > >
> > > > >
> > > > >
> > > > >
> > > > > >
> > > > > >   - /people/{uid}/@self            -- Return the COMPLETE
> > Profile
> > > > for
> > > > > >   user {uid}
> > > > > >   - /groups/{uid}/@self   -  Return ALL groups for user {uid}
> > > > > >
> > > > > >
> > > > > > Data Model (in the following, Level N+1 is inside Level N
> > object)
> > > > > >
> > > > > >   - *Level_1 * Person Object
> > > > > >   - *Level_2 * uid  String type
> > > > > >      - *Level_2 * set of all groups for this user
> > > > > >         - *Level_3  *groupid  (Reserved words: family, friends)
> > > > > >      - *Level_3 * for each group, contacts
> > > > > >            - *Level_4 * set of all contacts of in this group
> > > > > >            (set of Person objects identified by their uid)
> > > > > >
> > > > >
> > > > > Do we want to make each pid also be required to be a uid?  This
> > > > implies
> > > > > that pids cannot be relative in any implementation.  (If this is
> > just
> > > > > talking about the Shindig implementation then ignore this.)
> > > > >
> > > >
> > > > again my assumption is that each "contact" is also a "Person" in the
> > > > system
> > > > - the SAME "Person" object defined at Level_1.
> > > >
> > > > >
> > > > >
> > > > > >
> > > > > >
> > > > > >   - *Level_2 * User profile attributes
> > > > > >
> > > > > >         - *Level_3 * for each attribute, flag = public/private
> > > > > >         - *Level_3 * for each attribute, indicate which of the
> > > > > >         user's groups can view this attribute
> > > > > >            - *Level_4 *set of groups this attribute belongs to
> > > > > >
> > > > > > what do you say?
> > > > > >
> > > > > > On Wed, Apr 16, 2008 at 12:07 PM, John Panzer <
> > jpanzer@google.com>
> > > > > > wrote:
> > > > > >
> > > > > > > On Tue, Apr 15, 2008 at 4:43 PM, Robert Evans <
> > bobevans@google.com
> > > > >
> > > > > > wrote:
> > > > > > >
> > > > > > > > I am trying to think of the URIs as mapping to resources on
> > the
> > > > web,
> > > > > > and
> > > > > > > > trying to read it out loud. Consequently, please see the
> > reading
> > > > of
> > > > > > URIs
> > > > > > > > and
> > > > > > > > some questions/suggestions interspersed below.
> > > > > > > >
> > > > > > > > Thanks,
> > > > > > > > Bob
> > > > > > > >
> > > > > > > > On Mon, Apr 14, 2008 at 10:02 PM, David Primmer <
> > > > > > david.primmer@gmail.com
> > > > > > > >
> > > > > > > > wrote:
> > > > > > > >
> > > > > > > > > We're struggling with these implementation details right
> > now.
> > > > I'd
> > > > > > love
> > > > > > > > > to see what others have decided on.
> > > > > > > > >
> > > > > > > > > quick summary of the proposed url system (just for the
> > people
> > > > api)
> > > > > > > > >
> > > > > > > > > /people/{uid}/all            -- Collection of all people
> > > > connected
> > > > > > to
> > > > > > > > user
> > > > > > > > > {uid}
> > > > > > > >
> > > > > > > >
> > > > > > > > Sounds like: "Get people for user, {uid}; all of them."
> > > > > > >
> > > > > > >
> > > > > > > Yes (of course, it really just names the group of all people
> > > > connected
> > > > > > to
> > > > > > > user {uid}, you can do GET/PUT/POST/DELETE on this collection
> > > > > > depending on
> > > > > > > what you want to do).
> > > > > > >
> > > > > > >
> > > > > > > >
> > > > > > > >
> > > > > > > > >
> > > > > > > > > /people/{uid}/friends        -- Collection of all friends
> > of
> > > > user
> > > > > > > {uid};
> > > > > > > > > subset of all
> > > > > > > >
> > > > > > > >
> > > > > > > >  Sounds like: "Get people for user, {uid}; only those who
> > are
> > > > > > friends."
> > > > > > >
> > > > > > >
> > > > > > > Yep.
> > > > > > >
> > > > > > >
> > > > > > > >
> > > > > > > >
> > > > > > > > >
> > > > > > > > > /people/{uid}/{groupid}      -- Collection of all people
> > > > connected
> > > > > > to
> > > > > > > > user
> > > > > > > > > {uid} in group {groupid}
> > > > > > > >
> > > > > > > >
> > > > > > > > Sounds like: "Get people for user, {uid}; who are also in
> > > > group_id."
> > > > > > > >
> > > > > > > > That one is confusing. Won't this be the same as all people
> > in
> > > > > > {group
> > > > > > > id}?
> > > > > > > > I
> > > > > > > > have only a vague concept of "group" here, so please correct
> > > > that
> > > > > > for
> > > > > > > me.
> > > > > > >
> > > > > > >
> > > > > > > The concept here is that groups are user-relative too (see
> > below
> > > > for
> > > > > > > groups
> > > > > > > discussion).  My group "family" is much different from your
> > group
> > > > > > > "family".
> > > > > > > friends is really exactly this type of group.
> > > > > > >
> > > > > > >
> > > > > > > >
> > > > > > > >
> > > > > > > >
> > > > > > > > >
> > > > > > > > > /people/{uid}/all/{pid}      -- Individual person record.
> > > > > > > >
> > > > > > > >
> > > > > > > > Sounds like: "Get people for user, {uid}; All of them. Only
> > with
> > > > > > person
> > > > > > > > id,
> > > > > > > > {pid}."
> > > > > > > >
> > > > > > > > Why not drop the 'all'? /people/{uid}/{pid}
> > > > > > >
> > > > > > >
> > > > > > > I only put the "all" in there to make the URLs less confusing
> > --
> > > > > > anything
> > > > > > > at
> > > > > > > level 3 is always a person-id, anything at level 2 is always a
> > > > group
> > > > > > id.
> > > > > > > Conceptually you're saying "give me the person record as
> > accessed
> > > > > > through
> > > > > > > group 'X'".  Today people records are the same no matter what
> > > > group
> > > > > > you're
> > > > > > > in, but I could imagine wanting to change this (e.g., having a
> > > > > > > date-added-to-group field) which might vary depending on the
> > > > context.
> > > > > > >
> > > > > > >
> > > > > > >
> > > > > > > >
> > > > > > > >
> > > > > > > > Then it could sound like, "Get people for user, {uid}; with
> > > > person
> > > > > > id,
> > > > > > > > {pid}."
> > > > > > > > Sounds like: "Get people for user, {uid}, with person id
> > {pid}."
> > > > > > > >
> > > > > > > >
> > > > > > > > > /people/{uid}/sel            -- Self Profile record for
> > user
> > > > {uid}
> > > > > > > >
> > > > > > > >
> > > > > > > > Sounds like, "Get people for user, {uid}; sel."
> > > > > > > >
> > > > > > > > Why not drop the 'sel' here, and /people/{uid}/ just refers
> > to
> > > > that
> > > > > > user
> > > > > > > > resource specified by {uid}.
> > > > > > >
> > > > > > >
> > > > > > > We could probably drop @self (we added @ signs to make
> > meta-names
> > > > not
> > > > > > > conflict with regular names).  Thoughts?
> > > > > > >
> > > > > > >
> > > > > > > >
> > > > > > > >
> > > > > > > >
> > > > > > > > > /groups/{uid}/self           -- Collection of groups owned
> > by
> > > > the
> > > > > > > > > user, which always contains 'all' and 'friends' and may
> > > > contain
> > > > > > more.
> > > > > > > > > (Details TBD)
> > > > > > > > >
> > > > > > > > >
> > > > > > > > Sounds like: "Get groups for user, {uid}; self."
> > > > > > > > Perhaps, predicated on the group definition, it could just
> > be
> > > > > > > > /groups/{uid}
> > > > > > > > which gets all groups that user, {uid} belongs (owns?) to.
> > > > > > >
> > > > > > >
> > > > > > > The intended semantics are groups the user owns.  If we drop
> > @self
> > > > > > then it
> > > > > > > would just be /groups/{uid}
> > > > > > >
> > > > > > >
> > > > > > > >
> > > > > > > >
> > > > > > > > What is group ownership? Is the group any subset of people
> > that
> > > > a
> > > > > > user
> > > > > > > > knows?
> > > > > > > >
> > > > > > >
> > > > > > > A user can in principle set up any number of groups to
> > classify
> > > > the
> > > > > > people
> > > > > > > they know.  They get one special group by default, "friends".
> >  Not
> > > > > > > everybody
> > > > > > > they know is necessarily a friend.
> > > > > > >
> > > > > > > This is different from groups-you-belong-to in principle, in
> > that
> > > > you
> > > > > > can
> > > > > > > set up a group and stuff me in it without me being aware of it
> > or
> > > > > > caring.
> > > > > > > (Again, "friends" is special and has additional semantics --
> > it's
> > > > > > double
> > > > > > > opt
> > > > > > > in.  Other groups may have special semantics too, but the API
> > > > doesn't
> > > > > > > specify those semantics.)
> > > > > > >
> > > > > >
> > > > >
> > > > >
> > > > > >
> > > > >
> > > >
> > >
> > >
> > > >
> > >
> >
>
>
> --~--~---------~--~----~------------~-------~--~----~
> 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-unsubscribe@googlegroups.com
> For more options, visit this group at
> http://groups.google.com/group/opensocial-and-gadgets-spec?hl=en
> -~----------~----~----~----~------~----~------~--~---
>
>

Re: semantics of the restful server url templates

[Louis Ryan <lr...@google.com>]

The URI format used as examples so far seems a little prone to ambiguity?

/people/{uid}/{groupid}

is also a good match for

/people/{uid}/{photo-album-id}

especialy if we intend to allow the use of natural names as identifiers, as
in..

/people/me/friends

Are we intending to namespace the id's to avoid this issue or just namespace
by extending the URL pattern

/people/{uid}/groups/{groupid}

Thanks

-Louis



On Thu, Apr 17, 2008 at 6:18 PM, Vasu Nori <vn...@google.com> wrote:

> anyone has a comprehensive set of testdata for "People" to correspond with
> the datamodel discussed in this thread?
> just checking..
>
> On Wed, Apr 16, 2008 at 6:24 PM, John Panzer <jp...@google.com> wrote:
>
> >
> >
> > On Wed, Apr 16, 2008 at 6:08 PM, Vasu Nori <vn...@google.com> wrote:
> >
> > > On Wed, Apr 16, 2008 at 5:51 PM, John Panzer <jp...@google.com>
> wrote:
> > >
> > > > Looks good, some comments below:
> > > > (Also, + spec list as this is really overlapping with the spec)
> > > >
> > > > On Wed, Apr 16, 2008 at 2:05 PM, Vasu Nori <vn...@google.com> wrote:
> > > >
> > > > > Let me summarize People Restful API and the IMPLIED data model
> > > behind
> > > > > it.
> > > > >
> > > > > API calls
> > > > >
> > > > >   - /people/{uid}/all - Collection of all Public profiles for all
> > > users
> > > > >   connected with uid {uid}
> > > > >
> > > >
> > > > I'm not sure what Public profile means here -- specifically, I think
> > > it's
> > > > possible for a social network to implement an interface where the
> > > records
> > > > here are private to the user, or created by the user to describe
> > > people he
> > > > knows.  They could also be direct representations of a public or
> > > > semi-private profile of the target user of course, but I don't think
> > > > OpenSocial requires this semantic (right?)
> > > >
> > > >
> > > I made up the word "public".
> > > my most fundamental assumption is: A user has a set of attributes to
> > > decribe
> > > himself/herself. In this set,
> > > some attributes are set to be public
> > > and some are set to be completely private ("visible" ONLY to self)
> > > and some are set to be "visible" only to certain designated groups.
> > > does this make sense?
> > >
> > > if so, the above URL meaning is what I thought was said in the thread
> > > earlier by others.
> > >
> > > I am looking to validate my understanding really.
> >
> >
> > Ah, okay.  But I think this would interact with the access control of
> the
> > requestor.  There's of course a requester (which may be anonymous) in
> the
> > picture here.  Requestor might be different from both {uid} and {pid}.
> >
> >
> > >
> > >
> > > >
> > > > >
> > > > >   - /people/{uid}/friends        -- Collection of all Public
> > > profiles
> > > > >   for all users connected with user {uid} and group = "friends"
> > > > >   - /people/{uid}/{groupid}      -- Collection of all people
> > > connected
> > > > >    to user {uid} in group {groupid}
> > > > >    - /people/{uid}/@all/{pid}      -- Public profile, returning
> ALL
> > > > >   attributes of the user {pid} which are visible to ANY of the
> > > groups of
> > > > > user
> > > > >   {uid}
> > > > >
> > > >
> > > > Not quite sure what the above means (the "visible to ANY..." part)
> > > >
> > > "visible" = the attributes that are returnable in this/a query.
> > > maybe bad word..
> > >
> > > >
> > > >
> > > >
> > > > >
> > > > >   - /people/{uid}/@self            -- Return the COMPLETE Profile
> > > for
> > > > >   user {uid}
> > > > >   - /groups/{uid}/@self   -  Return ALL groups for user {uid}
> > > > >
> > > > >
> > > > > Data Model (in the following, Level N+1 is inside Level N object)
> > > > >
> > > > >   - *Level_1 * Person Object
> > > > >   - *Level_2 * uid  String type
> > > > >      - *Level_2 * set of all groups for this user
> > > > >         - *Level_3  *groupid  (Reserved words: family, friends)
> > > > >      - *Level_3 * for each group, contacts
> > > > >            - *Level_4 * set of all contacts of in this group
> > > > >            (set of Person objects identified by their uid)
> > > > >
> > > >
> > > > Do we want to make each pid also be required to be a uid?  This
> > > implies
> > > > that pids cannot be relative in any implementation.  (If this is
> just
> > > > talking about the Shindig implementation then ignore this.)
> > > >
> > >
> > > again my assumption is that each "contact" is also a "Person" in the
> > > system
> > > - the SAME "Person" object defined at Level_1.
> > >
> > > >
> > > >
> > > > >
> > > > >
> > > > >   - *Level_2 * User profile attributes
> > > > >
> > > > >         - *Level_3 * for each attribute, flag = public/private
> > > > >         - *Level_3 * for each attribute, indicate which of the
> > > > >         user's groups can view this attribute
> > > > >            - *Level_4 *set of groups this attribute belongs to
> > > > >
> > > > > what do you say?
> > > > >
> > > > > On Wed, Apr 16, 2008 at 12:07 PM, John Panzer <jp...@google.com>
> > > > > wrote:
> > > > >
> > > > > > On Tue, Apr 15, 2008 at 4:43 PM, Robert Evans <
> bobevans@google.com
> > > >
> > > > > wrote:
> > > > > >
> > > > > > > I am trying to think of the URIs as mapping to resources on
> the
> > > web,
> > > > > and
> > > > > > > trying to read it out loud. Consequently, please see the
> reading
> > > of
> > > > > URIs
> > > > > > > and
> > > > > > > some questions/suggestions interspersed below.
> > > > > > >
> > > > > > > Thanks,
> > > > > > > Bob
> > > > > > >
> > > > > > > On Mon, Apr 14, 2008 at 10:02 PM, David Primmer <
> > > > > david.primmer@gmail.com
> > > > > > >
> > > > > > > wrote:
> > > > > > >
> > > > > > > > We're struggling with these implementation details right
> now.
> > > I'd
> > > > > love
> > > > > > > > to see what others have decided on.
> > > > > > > >
> > > > > > > > quick summary of the proposed url system (just for the
> people
> > > api)
> > > > > > > >
> > > > > > > > /people/{uid}/all            -- Collection of all people
> > > connected
> > > > > to
> > > > > > > user
> > > > > > > > {uid}
> > > > > > >
> > > > > > >
> > > > > > > Sounds like: "Get people for user, {uid}; all of them."
> > > > > >
> > > > > >
> > > > > > Yes (of course, it really just names the group of all people
> > > connected
> > > > > to
> > > > > > user {uid}, you can do GET/PUT/POST/DELETE on this collection
> > > > > depending on
> > > > > > what you want to do).
> > > > > >
> > > > > >
> > > > > > >
> > > > > > >
> > > > > > > >
> > > > > > > > /people/{uid}/friends        -- Collection of all friends of
> > > user
> > > > > > {uid};
> > > > > > > > subset of all
> > > > > > >
> > > > > > >
> > > > > > >  Sounds like: "Get people for user, {uid}; only those who are
> > > > > friends."
> > > > > >
> > > > > >
> > > > > > Yep.
> > > > > >
> > > > > >
> > > > > > >
> > > > > > >
> > > > > > > >
> > > > > > > > /people/{uid}/{groupid}      -- Collection of all people
> > > connected
> > > > > to
> > > > > > > user
> > > > > > > > {uid} in group {groupid}
> > > > > > >
> > > > > > >
> > > > > > > Sounds like: "Get people for user, {uid}; who are also in
> > > group_id."
> > > > > > >
> > > > > > > That one is confusing. Won't this be the same as all people in
> > > > > {group
> > > > > > id}?
> > > > > > > I
> > > > > > > have only a vague concept of "group" here, so please correct
> > > that
> > > > > for
> > > > > > me.
> > > > > >
> > > > > >
> > > > > > The concept here is that groups are user-relative too (see below
> > > for
> > > > > > groups
> > > > > > discussion).  My group "family" is much different from your
> group
> > > > > > "family".
> > > > > > friends is really exactly this type of group.
> > > > > >
> > > > > >
> > > > > > >
> > > > > > >
> > > > > > >
> > > > > > > >
> > > > > > > > /people/{uid}/all/{pid}      -- Individual person record.
> > > > > > >
> > > > > > >
> > > > > > > Sounds like: "Get people for user, {uid}; All of them. Only
> with
> > > > > person
> > > > > > > id,
> > > > > > > {pid}."
> > > > > > >
> > > > > > > Why not drop the 'all'? /people/{uid}/{pid}
> > > > > >
> > > > > >
> > > > > > I only put the "all" in there to make the URLs less confusing --
> > > > > anything
> > > > > > at
> > > > > > level 3 is always a person-id, anything at level 2 is always a
> > > group
> > > > > id.
> > > > > > Conceptually you're saying "give me the person record as
> accessed
> > > > > through
> > > > > > group 'X'".  Today people records are the same no matter what
> > > group
> > > > > you're
> > > > > > in, but I could imagine wanting to change this (e.g., having a
> > > > > > date-added-to-group field) which might vary depending on the
> > > context.
> > > > > >
> > > > > >
> > > > > >
> > > > > > >
> > > > > > >
> > > > > > > Then it could sound like, "Get people for user, {uid}; with
> > > person
> > > > > id,
> > > > > > > {pid}."
> > > > > > > Sounds like: "Get people for user, {uid}, with person id
> {pid}."
> > > > > > >
> > > > > > >
> > > > > > > > /people/{uid}/sel            -- Self Profile record for user
> > > {uid}
> > > > > > >
> > > > > > >
> > > > > > > Sounds like, "Get people for user, {uid}; sel."
> > > > > > >
> > > > > > > Why not drop the 'sel' here, and /people/{uid}/ just refers to
> > > that
> > > > > user
> > > > > > > resource specified by {uid}.
> > > > > >
> > > > > >
> > > > > > We could probably drop @self (we added @ signs to make
> meta-names
> > > not
> > > > > > conflict with regular names).  Thoughts?
> > > > > >
> > > > > >
> > > > > > >
> > > > > > >
> > > > > > >
> > > > > > > > /groups/{uid}/self           -- Collection of groups owned
> by
> > > the
> > > > > > > > user, which always contains 'all' and 'friends' and may
> > > contain
> > > > > more.
> > > > > > > > (Details TBD)
> > > > > > > >
> > > > > > > >
> > > > > > > Sounds like: "Get groups for user, {uid}; self."
> > > > > > > Perhaps, predicated on the group definition, it could just be
> > > > > > > /groups/{uid}
> > > > > > > which gets all groups that user, {uid} belongs (owns?) to.
> > > > > >
> > > > > >
> > > > > > The intended semantics are groups the user owns.  If we drop
> @self
> > > > > then it
> > > > > > would just be /groups/{uid}
> > > > > >
> > > > > >
> > > > > > >
> > > > > > >
> > > > > > > What is group ownership? Is the group any subset of people
> that
> > > a
> > > > > user
> > > > > > > knows?
> > > > > > >
> > > > > >
> > > > > > A user can in principle set up any number of groups to classify
> > > the
> > > > > people
> > > > > > they know.  They get one special group by default, "friends".
>  Not
> > > > > > everybody
> > > > > > they know is necessarily a friend.
> > > > > >
> > > > > > This is different from groups-you-belong-to in principle, in
> that
> > > you
> > > > > can
> > > > > > set up a group and stuff me in it without me being aware of it
> or
> > > > > caring.
> > > > > > (Again, "friends" is special and has additional semantics --
> it's
> > > > > double
> > > > > > opt
> > > > > > in.  Other groups may have special semantics too, but the API
> > > doesn't
> > > > > > specify those semantics.)
> > > > > >
> > > > >
> > > >
> > > >
> > > > >
> > > >
> > >
> >
> >
> > --~--~---------~--~----~------------~-------~--~----~
> > 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-unsubscribe@googlegroups.com
> > For more options, visit this group at
> > http://groups.google.com/group/opensocial-and-gadgets-spec?hl=en
> > -~----------~----~----~----~------~----~------~--~---
> >
> >
>

Re: semantics of the restful server url templates

[Vasu Nori <vn...@google.com>]

anyone has a comprehensive set of testdata for "People" to correspond with
the datamodel discussed in this thread?
just checking..

On Wed, Apr 16, 2008 at 6:24 PM, John Panzer <jp...@google.com> wrote:

>
>
> On Wed, Apr 16, 2008 at 6:08 PM, Vasu Nori <vn...@google.com> wrote:
>
> > On Wed, Apr 16, 2008 at 5:51 PM, John Panzer <jp...@google.com> wrote:
> >
> > > Looks good, some comments below:
> > > (Also, + spec list as this is really overlapping with the spec)
> > >
> > > On Wed, Apr 16, 2008 at 2:05 PM, Vasu Nori <vn...@google.com> wrote:
> > >
> > > > Let me summarize People Restful API and the IMPLIED data model
> > behind
> > > > it.
> > > >
> > > > API calls
> > > >
> > > >   - /people/{uid}/all - Collection of all Public profiles for all
> > users
> > > >   connected with uid {uid}
> > > >
> > >
> > > I'm not sure what Public profile means here -- specifically, I think
> > it's
> > > possible for a social network to implement an interface where the
> > records
> > > here are private to the user, or created by the user to describe
> > people he
> > > knows.  They could also be direct representations of a public or
> > > semi-private profile of the target user of course, but I don't think
> > > OpenSocial requires this semantic (right?)
> > >
> > >
> > I made up the word "public".
> > my most fundamental assumption is: A user has a set of attributes to
> > decribe
> > himself/herself. In this set,
> > some attributes are set to be public
> > and some are set to be completely private ("visible" ONLY to self)
> > and some are set to be "visible" only to certain designated groups.
> > does this make sense?
> >
> > if so, the above URL meaning is what I thought was said in the thread
> > earlier by others.
> >
> > I am looking to validate my understanding really.
>
>
> Ah, okay.  But I think this would interact with the access control of the
> requestor.  There's of course a requester (which may be anonymous) in the
> picture here.  Requestor might be different from both {uid} and {pid}.
>
>
> >
> >
> > >
> > > >
> > > >   - /people/{uid}/friends        -- Collection of all Public
> > profiles
> > > >   for all users connected with user {uid} and group = "friends"
> > > >   - /people/{uid}/{groupid}      -- Collection of all people
> > connected
> > > >    to user {uid} in group {groupid}
> > > >    - /people/{uid}/@all/{pid}      -- Public profile, returning ALL
> > > >   attributes of the user {pid} which are visible to ANY of the
> > groups of
> > > > user
> > > >   {uid}
> > > >
> > >
> > > Not quite sure what the above means (the "visible to ANY..." part)
> > >
> > "visible" = the attributes that are returnable in this/a query.
> > maybe bad word..
> >
> > >
> > >
> > >
> > > >
> > > >   - /people/{uid}/@self            -- Return the COMPLETE Profile
> > for
> > > >   user {uid}
> > > >   - /groups/{uid}/@self   -  Return ALL groups for user {uid}
> > > >
> > > >
> > > > Data Model (in the following, Level N+1 is inside Level N object)
> > > >
> > > >   - *Level_1 * Person Object
> > > >   - *Level_2 * uid  String type
> > > >      - *Level_2 * set of all groups for this user
> > > >         - *Level_3  *groupid  (Reserved words: family, friends)
> > > >      - *Level_3 * for each group, contacts
> > > >            - *Level_4 * set of all contacts of in this group
> > > >            (set of Person objects identified by their uid)
> > > >
> > >
> > > Do we want to make each pid also be required to be a uid?  This
> > implies
> > > that pids cannot be relative in any implementation.  (If this is just
> > > talking about the Shindig implementation then ignore this.)
> > >
> >
> > again my assumption is that each "contact" is also a "Person" in the
> > system
> > - the SAME "Person" object defined at Level_1.
> >
> > >
> > >
> > > >
> > > >
> > > >   - *Level_2 * User profile attributes
> > > >
> > > >         - *Level_3 * for each attribute, flag = public/private
> > > >         - *Level_3 * for each attribute, indicate which of the
> > > >         user's groups can view this attribute
> > > >            - *Level_4 *set of groups this attribute belongs to
> > > >
> > > > what do you say?
> > > >
> > > > On Wed, Apr 16, 2008 at 12:07 PM, John Panzer <jp...@google.com>
> > > > wrote:
> > > >
> > > > > On Tue, Apr 15, 2008 at 4:43 PM, Robert Evans <bobevans@google.com
> > >
> > > > wrote:
> > > > >
> > > > > > I am trying to think of the URIs as mapping to resources on the
> > web,
> > > > and
> > > > > > trying to read it out loud. Consequently, please see the reading
> > of
> > > > URIs
> > > > > > and
> > > > > > some questions/suggestions interspersed below.
> > > > > >
> > > > > > Thanks,
> > > > > > Bob
> > > > > >
> > > > > > On Mon, Apr 14, 2008 at 10:02 PM, David Primmer <
> > > > david.primmer@gmail.com
> > > > > >
> > > > > > wrote:
> > > > > >
> > > > > > > We're struggling with these implementation details right now.
> > I'd
> > > > love
> > > > > > > to see what others have decided on.
> > > > > > >
> > > > > > > quick summary of the proposed url system (just for the people
> > api)
> > > > > > >
> > > > > > > /people/{uid}/all            -- Collection of all people
> > connected
> > > > to
> > > > > > user
> > > > > > > {uid}
> > > > > >
> > > > > >
> > > > > > Sounds like: "Get people for user, {uid}; all of them."
> > > > >
> > > > >
> > > > > Yes (of course, it really just names the group of all people
> > connected
> > > > to
> > > > > user {uid}, you can do GET/PUT/POST/DELETE on this collection
> > > > depending on
> > > > > what you want to do).
> > > > >
> > > > >
> > > > > >
> > > > > >
> > > > > > >
> > > > > > > /people/{uid}/friends        -- Collection of all friends of
> > user
> > > > > {uid};
> > > > > > > subset of all
> > > > > >
> > > > > >
> > > > > >  Sounds like: "Get people for user, {uid}; only those who are
> > > > friends."
> > > > >
> > > > >
> > > > > Yep.
> > > > >
> > > > >
> > > > > >
> > > > > >
> > > > > > >
> > > > > > > /people/{uid}/{groupid}      -- Collection of all people
> > connected
> > > > to
> > > > > > user
> > > > > > > {uid} in group {groupid}
> > > > > >
> > > > > >
> > > > > > Sounds like: "Get people for user, {uid}; who are also in
> > group_id."
> > > > > >
> > > > > > That one is confusing. Won't this be the same as all people in
> > > > {group
> > > > > id}?
> > > > > > I
> > > > > > have only a vague concept of "group" here, so please correct
> > that
> > > > for
> > > > > me.
> > > > >
> > > > >
> > > > > The concept here is that groups are user-relative too (see below
> > for
> > > > > groups
> > > > > discussion).  My group "family" is much different from your group
> > > > > "family".
> > > > > friends is really exactly this type of group.
> > > > >
> > > > >
> > > > > >
> > > > > >
> > > > > >
> > > > > > >
> > > > > > > /people/{uid}/all/{pid}      -- Individual person record.
> > > > > >
> > > > > >
> > > > > > Sounds like: "Get people for user, {uid}; All of them. Only with
> > > > person
> > > > > > id,
> > > > > > {pid}."
> > > > > >
> > > > > > Why not drop the 'all'? /people/{uid}/{pid}
> > > > >
> > > > >
> > > > > I only put the "all" in there to make the URLs less confusing --
> > > > anything
> > > > > at
> > > > > level 3 is always a person-id, anything at level 2 is always a
> > group
> > > > id.
> > > > > Conceptually you're saying "give me the person record as accessed
> > > > through
> > > > > group 'X'".  Today people records are the same no matter what
> > group
> > > > you're
> > > > > in, but I could imagine wanting to change this (e.g., having a
> > > > > date-added-to-group field) which might vary depending on the
> > context.
> > > > >
> > > > >
> > > > >
> > > > > >
> > > > > >
> > > > > > Then it could sound like, "Get people for user, {uid}; with
> > person
> > > > id,
> > > > > > {pid}."
> > > > > > Sounds like: "Get people for user, {uid}, with person id {pid}."
> > > > > >
> > > > > >
> > > > > > > /people/{uid}/sel            -- Self Profile record for user
> > {uid}
> > > > > >
> > > > > >
> > > > > > Sounds like, "Get people for user, {uid}; sel."
> > > > > >
> > > > > > Why not drop the 'sel' here, and /people/{uid}/ just refers to
> > that
> > > > user
> > > > > > resource specified by {uid}.
> > > > >
> > > > >
> > > > > We could probably drop @self (we added @ signs to make meta-names
> > not
> > > > > conflict with regular names).  Thoughts?
> > > > >
> > > > >
> > > > > >
> > > > > >
> > > > > >
> > > > > > > /groups/{uid}/self           -- Collection of groups owned by
> > the
> > > > > > > user, which always contains 'all' and 'friends' and may
> > contain
> > > > more.
> > > > > > > (Details TBD)
> > > > > > >
> > > > > > >
> > > > > > Sounds like: "Get groups for user, {uid}; self."
> > > > > > Perhaps, predicated on the group definition, it could just be
> > > > > > /groups/{uid}
> > > > > > which gets all groups that user, {uid} belongs (owns?) to.
> > > > >
> > > > >
> > > > > The intended semantics are groups the user owns.  If we drop @self
> > > > then it
> > > > > would just be /groups/{uid}
> > > > >
> > > > >
> > > > > >
> > > > > >
> > > > > > What is group ownership? Is the group any subset of people that
> > a
> > > > user
> > > > > > knows?
> > > > > >
> > > > >
> > > > > A user can in principle set up any number of groups to classify
> > the
> > > > people
> > > > > they know.  They get one special group by default, "friends".  Not
> > > > > everybody
> > > > > they know is necessarily a friend.
> > > > >
> > > > > This is different from groups-you-belong-to in principle, in that
> > you
> > > > can
> > > > > set up a group and stuff me in it without me being aware of it or
> > > > caring.
> > > > > (Again, "friends" is special and has additional semantics -- it's
> > > > double
> > > > > opt
> > > > > in.  Other groups may have special semantics too, but the API
> > doesn't
> > > > > specify those semantics.)
> > > > >
> > > >
> > >
> > >
> > > >
> > >
> >
>
>
> --~--~---------~--~----~------------~-------~--~----~
> 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-unsubscribe@googlegroups.com
> For more options, visit this group at
> http://groups.google.com/group/opensocial-and-gadgets-spec?hl=en
> -~----------~----~----~----~------~----~------~--~---
>
>

Re: semantics of the restful server url templates

[John Panzer <jp...@google.com>]

On Wed, Apr 16, 2008 at 6:08 PM, Vasu Nori <vn...@google.com> wrote:

> On Wed, Apr 16, 2008 at 5:51 PM, John Panzer <jp...@google.com> wrote:
>
> > Looks good, some comments below:
> > (Also, + spec list as this is really overlapping with the spec)
> >
> > On Wed, Apr 16, 2008 at 2:05 PM, Vasu Nori <vn...@google.com> wrote:
> >
> > > Let me summarize People Restful API and the IMPLIED data model behind
> > > it.
> > >
> > > API calls
> > >
> > >   - /people/{uid}/all - Collection of all Public profiles for all
> users
> > >   connected with uid {uid}
> > >
> >
> > I'm not sure what Public profile means here -- specifically, I think
> it's
> > possible for a social network to implement an interface where the
> records
> > here are private to the user, or created by the user to describe people
> he
> > knows.  They could also be direct representations of a public or
> > semi-private profile of the target user of course, but I don't think
> > OpenSocial requires this semantic (right?)
> >
> >
> I made up the word "public".
> my most fundamental assumption is: A user has a set of attributes to
> decribe
> himself/herself. In this set,
> some attributes are set to be public
> and some are set to be completely private ("visible" ONLY to self)
> and some are set to be "visible" only to certain designated groups.
> does this make sense?
>
> if so, the above URL meaning is what I thought was said in the thread
> earlier by others.
>
> I am looking to validate my understanding really.


Ah, okay.  But I think this would interact with the access control of the
requestor.  There's of course a requester (which may be anonymous) in the
picture here.  Requestor might be different from both {uid} and {pid}.


>
>
> >
> > >
> > >   - /people/{uid}/friends        -- Collection of all Public profiles
> > >   for all users connected with user {uid} and group = "friends"
> > >   - /people/{uid}/{groupid}      -- Collection of all people connected
> > >    to user {uid} in group {groupid}
> > >    - /people/{uid}/@all/{pid}      -- Public profile, returning ALL
> > >   attributes of the user {pid} which are visible to ANY of the groups
> of
> > > user
> > >   {uid}
> > >
> >
> > Not quite sure what the above means (the "visible to ANY..." part)
> >
> "visible" = the attributes that are returnable in this/a query.
> maybe bad word..
>
> >
> >
> >
> > >
> > >   - /people/{uid}/@self            -- Return the COMPLETE Profile for
> > >   user {uid}
> > >   - /groups/{uid}/@self   -  Return ALL groups for user {uid}
> > >
> > >
> > > Data Model (in the following, Level N+1 is inside Level N object)
> > >
> > >   - *Level_1 * Person Object
> > >   - *Level_2 * uid  String type
> > >      - *Level_2 * set of all groups for this user
> > >         - *Level_3  *groupid  (Reserved words: family, friends)
> > >      - *Level_3 * for each group, contacts
> > >            - *Level_4 * set of all contacts of in this group
> > >            (set of Person objects identified by their uid)
> > >
> >
> > Do we want to make each pid also be required to be a uid?  This implies
> > that pids cannot be relative in any implementation.  (If this is just
> > talking about the Shindig implementation then ignore this.)
> >
>
> again my assumption is that each "contact" is also a "Person" in the
> system
> - the SAME "Person" object defined at Level_1.
>
> >
> >
> > >
> > >
> > >   - *Level_2 * User profile attributes
> > >
> > >         - *Level_3 * for each attribute, flag = public/private
> > >         - *Level_3 * for each attribute, indicate which of the
> > >         user's groups can view this attribute
> > >            - *Level_4 *set of groups this attribute belongs to
> > >
> > > what do you say?
> > >
> > > On Wed, Apr 16, 2008 at 12:07 PM, John Panzer <jp...@google.com>
> > > wrote:
> > >
> > > > On Tue, Apr 15, 2008 at 4:43 PM, Robert Evans <bo...@google.com>
> > > wrote:
> > > >
> > > > > I am trying to think of the URIs as mapping to resources on the
> web,
> > > and
> > > > > trying to read it out loud. Consequently, please see the reading
> of
> > > URIs
> > > > > and
> > > > > some questions/suggestions interspersed below.
> > > > >
> > > > > Thanks,
> > > > > Bob
> > > > >
> > > > > On Mon, Apr 14, 2008 at 10:02 PM, David Primmer <
> > > david.primmer@gmail.com
> > > > >
> > > > > wrote:
> > > > >
> > > > > > We're struggling with these implementation details right now.
> I'd
> > > love
> > > > > > to see what others have decided on.
> > > > > >
> > > > > > quick summary of the proposed url system (just for the people
> api)
> > > > > >
> > > > > > /people/{uid}/all            -- Collection of all people
> connected
> > > to
> > > > > user
> > > > > > {uid}
> > > > >
> > > > >
> > > > > Sounds like: "Get people for user, {uid}; all of them."
> > > >
> > > >
> > > > Yes (of course, it really just names the group of all people
> connected
> > > to
> > > > user {uid}, you can do GET/PUT/POST/DELETE on this collection
> > > depending on
> > > > what you want to do).
> > > >
> > > >
> > > > >
> > > > >
> > > > > >
> > > > > > /people/{uid}/friends        -- Collection of all friends of
> user
> > > > {uid};
> > > > > > subset of all
> > > > >
> > > > >
> > > > >  Sounds like: "Get people for user, {uid}; only those who are
> > > friends."
> > > >
> > > >
> > > > Yep.
> > > >
> > > >
> > > > >
> > > > >
> > > > > >
> > > > > > /people/{uid}/{groupid}      -- Collection of all people
> connected
> > > to
> > > > > user
> > > > > > {uid} in group {groupid}
> > > > >
> > > > >
> > > > > Sounds like: "Get people for user, {uid}; who are also in
> group_id."
> > > > >
> > > > > That one is confusing. Won't this be the same as all people in
> > > {group
> > > > id}?
> > > > > I
> > > > > have only a vague concept of "group" here, so please correct that
> > > for
> > > > me.
> > > >
> > > >
> > > > The concept here is that groups are user-relative too (see below for
> > > > groups
> > > > discussion).  My group "family" is much different from your group
> > > > "family".
> > > > friends is really exactly this type of group.
> > > >
> > > >
> > > > >
> > > > >
> > > > >
> > > > > >
> > > > > > /people/{uid}/all/{pid}      -- Individual person record.
> > > > >
> > > > >
> > > > > Sounds like: "Get people for user, {uid}; All of them. Only with
> > > person
> > > > > id,
> > > > > {pid}."
> > > > >
> > > > > Why not drop the 'all'? /people/{uid}/{pid}
> > > >
> > > >
> > > > I only put the "all" in there to make the URLs less confusing --
> > > anything
> > > > at
> > > > level 3 is always a person-id, anything at level 2 is always a group
> > > id.
> > > > Conceptually you're saying "give me the person record as accessed
> > > through
> > > > group 'X'".  Today people records are the same no matter what group
> > > you're
> > > > in, but I could imagine wanting to change this (e.g., having a
> > > > date-added-to-group field) which might vary depending on the
> context.
> > > >
> > > >
> > > >
> > > > >
> > > > >
> > > > > Then it could sound like, "Get people for user, {uid}; with person
> > > id,
> > > > > {pid}."
> > > > > Sounds like: "Get people for user, {uid}, with person id {pid}."
> > > > >
> > > > >
> > > > > > /people/{uid}/sel            -- Self Profile record for user
> {uid}
> > > > >
> > > > >
> > > > > Sounds like, "Get people for user, {uid}; sel."
> > > > >
> > > > > Why not drop the 'sel' here, and /people/{uid}/ just refers to
> that
> > > user
> > > > > resource specified by {uid}.
> > > >
> > > >
> > > > We could probably drop @self (we added @ signs to make meta-names
> not
> > > > conflict with regular names).  Thoughts?
> > > >
> > > >
> > > > >
> > > > >
> > > > >
> > > > > > /groups/{uid}/self           -- Collection of groups owned by
> the
> > > > > > user, which always contains 'all' and 'friends' and may contain
> > > more.
> > > > > > (Details TBD)
> > > > > >
> > > > > >
> > > > > Sounds like: "Get groups for user, {uid}; self."
> > > > > Perhaps, predicated on the group definition, it could just be
> > > > > /groups/{uid}
> > > > > which gets all groups that user, {uid} belongs (owns?) to.
> > > >
> > > >
> > > > The intended semantics are groups the user owns.  If we drop @self
> > > then it
> > > > would just be /groups/{uid}
> > > >
> > > >
> > > > >
> > > > >
> > > > > What is group ownership? Is the group any subset of people that a
> > > user
> > > > > knows?
> > > > >
> > > >
> > > > A user can in principle set up any number of groups to classify the
> > > people
> > > > they know.  They get one special group by default, "friends".  Not
> > > > everybody
> > > > they know is necessarily a friend.
> > > >
> > > > This is different from groups-you-belong-to in principle, in that
> you
> > > can
> > > > set up a group and stuff me in it without me being aware of it or
> > > caring.
> > > > (Again, "friends" is special and has additional semantics -- it's
> > > double
> > > > opt
> > > > in.  Other groups may have special semantics too, but the API
> doesn't
> > > > specify those semantics.)
> > > >
> > >
> >
> >
> > --~--~---------~--~----~------------~-------~--~----~
> > 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-unsubscribe@googlegroups.com
> > For more options, visit this group at
> > http://groups.google.com/group/opensocial-and-gadgets-spec?hl=en
> > -~----------~----~----~----~------~----~------~--~---
> >
> >
>

Re: semantics of the restful server url templates

[Vasu Nori <vn...@google.com>]

On Wed, Apr 16, 2008 at 5:51 PM, John Panzer <jp...@google.com> wrote:

> Looks good, some comments below:
> (Also, + spec list as this is really overlapping with the spec)
>
> On Wed, Apr 16, 2008 at 2:05 PM, Vasu Nori <vn...@google.com> wrote:
>
> > Let me summarize People Restful API and the IMPLIED data model behind
> > it.
> >
> > API calls
> >
> >   - /people/{uid}/all - Collection of all Public profiles for all users
> >   connected with uid {uid}
> >
>
> I'm not sure what Public profile means here -- specifically, I think it's
> possible for a social network to implement an interface where the records
> here are private to the user, or created by the user to describe people he
> knows.  They could also be direct representations of a public or
> semi-private profile of the target user of course, but I don't think
> OpenSocial requires this semantic (right?)
>
>
I made up the word "public".
my most fundamental assumption is: A user has a set of attributes to decribe
himself/herself. In this set,
some attributes are set to be public
and some are set to be completely private ("visible" ONLY to self)
and some are set to be "visible" only to certain designated groups.
does this make sense?

if so, the above URL meaning is what I thought was said in the thread
earlier by others.

I am looking to validate my understanding really.

>
> >
> >   - /people/{uid}/friends        -- Collection of all Public profiles
> >   for all users connected with user {uid} and group = "friends"
> >   - /people/{uid}/{groupid}      -- Collection of all people connected
> >    to user {uid} in group {groupid}
> >    - /people/{uid}/@all/{pid}      -- Public profile, returning ALL
> >   attributes of the user {pid} which are visible to ANY of the groups of
> > user
> >   {uid}
> >
>
> Not quite sure what the above means (the "visible to ANY..." part)
>
"visible" = the attributes that are returnable in this/a query.
maybe bad word..

>
>
>
> >
> >   - /people/{uid}/@self            -- Return the COMPLETE Profile for
> >   user {uid}
> >   - /groups/{uid}/@self   -  Return ALL groups for user {uid}
> >
> >
> > Data Model (in the following, Level N+1 is inside Level N object)
> >
> >   - *Level_1 * Person Object
> >   - *Level_2 * uid  String type
> >      - *Level_2 * set of all groups for this user
> >         - *Level_3  *groupid  (Reserved words: family, friends)
> >      - *Level_3 * for each group, contacts
> >            - *Level_4 * set of all contacts of in this group
> >            (set of Person objects identified by their uid)
> >
>
> Do we want to make each pid also be required to be a uid?  This implies
> that pids cannot be relative in any implementation.  (If this is just
> talking about the Shindig implementation then ignore this.)
>

again my assumption is that each "contact" is also a "Person" in the system
- the SAME "Person" object defined at Level_1.

>
>
> >
> >
> >   - *Level_2 * User profile attributes
> >
> >         - *Level_3 * for each attribute, flag = public/private
> >         - *Level_3 * for each attribute, indicate which of the
> >         user's groups can view this attribute
> >            - *Level_4 *set of groups this attribute belongs to
> >
> > what do you say?
> >
> > On Wed, Apr 16, 2008 at 12:07 PM, John Panzer <jp...@google.com>
> > wrote:
> >
> > > On Tue, Apr 15, 2008 at 4:43 PM, Robert Evans <bo...@google.com>
> > wrote:
> > >
> > > > I am trying to think of the URIs as mapping to resources on the web,
> > and
> > > > trying to read it out loud. Consequently, please see the reading of
> > URIs
> > > > and
> > > > some questions/suggestions interspersed below.
> > > >
> > > > Thanks,
> > > > Bob
> > > >
> > > > On Mon, Apr 14, 2008 at 10:02 PM, David Primmer <
> > david.primmer@gmail.com
> > > >
> > > > wrote:
> > > >
> > > > > We're struggling with these implementation details right now. I'd
> > love
> > > > > to see what others have decided on.
> > > > >
> > > > > quick summary of the proposed url system (just for the people api)
> > > > >
> > > > > /people/{uid}/all            -- Collection of all people connected
> > to
> > > > user
> > > > > {uid}
> > > >
> > > >
> > > > Sounds like: "Get people for user, {uid}; all of them."
> > >
> > >
> > > Yes (of course, it really just names the group of all people connected
> > to
> > > user {uid}, you can do GET/PUT/POST/DELETE on this collection
> > depending on
> > > what you want to do).
> > >
> > >
> > > >
> > > >
> > > > >
> > > > > /people/{uid}/friends        -- Collection of all friends of user
> > > {uid};
> > > > > subset of all
> > > >
> > > >
> > > >  Sounds like: "Get people for user, {uid}; only those who are
> > friends."
> > >
> > >
> > > Yep.
> > >
> > >
> > > >
> > > >
> > > > >
> > > > > /people/{uid}/{groupid}      -- Collection of all people connected
> > to
> > > > user
> > > > > {uid} in group {groupid}
> > > >
> > > >
> > > > Sounds like: "Get people for user, {uid}; who are also in group_id."
> > > >
> > > > That one is confusing. Won't this be the same as all people in
> > {group
> > > id}?
> > > > I
> > > > have only a vague concept of "group" here, so please correct that
> > for
> > > me.
> > >
> > >
> > > The concept here is that groups are user-relative too (see below for
> > > groups
> > > discussion).  My group "family" is much different from your group
> > > "family".
> > > friends is really exactly this type of group.
> > >
> > >
> > > >
> > > >
> > > >
> > > > >
> > > > > /people/{uid}/all/{pid}      -- Individual person record.
> > > >
> > > >
> > > > Sounds like: "Get people for user, {uid}; All of them. Only with
> > person
> > > > id,
> > > > {pid}."
> > > >
> > > > Why not drop the 'all'? /people/{uid}/{pid}
> > >
> > >
> > > I only put the "all" in there to make the URLs less confusing --
> > anything
> > > at
> > > level 3 is always a person-id, anything at level 2 is always a group
> > id.
> > > Conceptually you're saying "give me the person record as accessed
> > through
> > > group 'X'".  Today people records are the same no matter what group
> > you're
> > > in, but I could imagine wanting to change this (e.g., having a
> > > date-added-to-group field) which might vary depending on the context.
> > >
> > >
> > >
> > > >
> > > >
> > > > Then it could sound like, "Get people for user, {uid}; with person
> > id,
> > > > {pid}."
> > > > Sounds like: "Get people for user, {uid}, with person id {pid}."
> > > >
> > > >
> > > > > /people/{uid}/sel            -- Self Profile record for user {uid}
> > > >
> > > >
> > > > Sounds like, "Get people for user, {uid}; sel."
> > > >
> > > > Why not drop the 'sel' here, and /people/{uid}/ just refers to that
> > user
> > > > resource specified by {uid}.
> > >
> > >
> > > We could probably drop @self (we added @ signs to make meta-names not
> > > conflict with regular names).  Thoughts?
> > >
> > >
> > > >
> > > >
> > > >
> > > > > /groups/{uid}/self           -- Collection of groups owned by the
> > > > > user, which always contains 'all' and 'friends' and may contain
> > more.
> > > > > (Details TBD)
> > > > >
> > > > >
> > > > Sounds like: "Get groups for user, {uid}; self."
> > > > Perhaps, predicated on the group definition, it could just be
> > > > /groups/{uid}
> > > > which gets all groups that user, {uid} belongs (owns?) to.
> > >
> > >
> > > The intended semantics are groups the user owns.  If we drop @self
> > then it
> > > would just be /groups/{uid}
> > >
> > >
> > > >
> > > >
> > > > What is group ownership? Is the group any subset of people that a
> > user
> > > > knows?
> > > >
> > >
> > > A user can in principle set up any number of groups to classify the
> > people
> > > they know.  They get one special group by default, "friends".  Not
> > > everybody
> > > they know is necessarily a friend.
> > >
> > > This is different from groups-you-belong-to in principle, in that you
> > can
> > > set up a group and stuff me in it without me being aware of it or
> > caring.
> > > (Again, "friends" is special and has additional semantics -- it's
> > double
> > > opt
> > > in.  Other groups may have special semantics too, but the API doesn't
> > > specify those semantics.)
> > >
> >
>
>
> --~--~---------~--~----~------------~-------~--~----~
> 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-unsubscribe@googlegroups.com
> For more options, visit this group at
> http://groups.google.com/group/opensocial-and-gadgets-spec?hl=en
> -~----------~----~----~----~------~----~------~--~---
>
>

Re: semantics of the restful server url templates

[John Panzer <jp...@google.com>]

Looks good, some comments below:
(Also, + spec list as this is really overlapping with the spec)

On Wed, Apr 16, 2008 at 2:05 PM, Vasu Nori <vn...@google.com> wrote:

> Let me summarize People Restful API and the IMPLIED data model behind it.
>
> API calls
>
>   - /people/{uid}/all - Collection of all Public profiles for all users
>   connected with uid {uid}
>

I'm not sure what Public profile means here -- specifically, I think it's
possible for a social network to implement an interface where the records
here are private to the user, or created by the user to describe people he
knows.  They could also be direct representations of a public or
semi-private profile of the target user of course, but I don't think
OpenSocial requires this semantic (right?)


>
>
>   - /people/{uid}/friends        -- Collection of all Public profiles
>   for all users connected with user {uid} and group = "friends"
>   - /people/{uid}/{groupid}      -- Collection of all people connected
>    to user {uid} in group {groupid}
>    - /people/{uid}/@all/{pid}      -- Public profile, returning ALL
>   attributes of the user {pid} which are visible to ANY of the groups of
> user
>   {uid}


Not quite sure what the above means (the "visible to ANY..." part)


>
>   - /people/{uid}/@self            -- Return the COMPLETE Profile for
>   user {uid}
>   - /groups/{uid}/@self   -  Return ALL groups for user {uid}
>
>
> Data Model (in the following, Level N+1 is inside Level N object)
>
>   - *Level_1 * Person Object
>   - *Level_2 * uid  String type
>      - *Level_2 * set of all groups for this user
>         - *Level_3  *groupid  (Reserved words: family, friends)
>      - *Level_3 * for each group, contacts
>            - *Level_4 * set of all contacts of in this group
>            (set of Person objects identified by their uid)


Do we want to make each pid also be required to be a uid?  This implies that
pids cannot be relative in any implementation.  (If this is just talking
about the Shindig implementation then ignore this.)

>
>
>
>   - *Level_2 * User profile attributes
>         - *Level_3 * for each attribute, flag = public/private
>         - *Level_3 * for each attribute, indicate which of the
>         user's groups can view this attribute
>            - *Level_4 *set of groups this attribute belongs to
>
> what do you say?
>
> On Wed, Apr 16, 2008 at 12:07 PM, John Panzer <jp...@google.com> wrote:
>
> > On Tue, Apr 15, 2008 at 4:43 PM, Robert Evans <bo...@google.com>
> wrote:
> >
> > > I am trying to think of the URIs as mapping to resources on the web,
> and
> > > trying to read it out loud. Consequently, please see the reading of
> URIs
> > > and
> > > some questions/suggestions interspersed below.
> > >
> > > Thanks,
> > > Bob
> > >
> > > On Mon, Apr 14, 2008 at 10:02 PM, David Primmer <
> david.primmer@gmail.com
> > >
> > > wrote:
> > >
> > > > We're struggling with these implementation details right now. I'd
> love
> > > > to see what others have decided on.
> > > >
> > > > quick summary of the proposed url system (just for the people api)
> > > >
> > > > /people/{uid}/all            -- Collection of all people connected
> to
> > > user
> > > > {uid}
> > >
> > >
> > > Sounds like: "Get people for user, {uid}; all of them."
> >
> >
> > Yes (of course, it really just names the group of all people connected
> to
> > user {uid}, you can do GET/PUT/POST/DELETE on this collection depending
> on
> > what you want to do).
> >
> >
> > >
> > >
> > > >
> > > > /people/{uid}/friends        -- Collection of all friends of user
> > {uid};
> > > > subset of all
> > >
> > >
> > >  Sounds like: "Get people for user, {uid}; only those who are
> friends."
> >
> >
> > Yep.
> >
> >
> > >
> > >
> > > >
> > > > /people/{uid}/{groupid}      -- Collection of all people connected
> to
> > > user
> > > > {uid} in group {groupid}
> > >
> > >
> > > Sounds like: "Get people for user, {uid}; who are also in group_id."
> > >
> > > That one is confusing. Won't this be the same as all people in {group
> > id}?
> > > I
> > > have only a vague concept of "group" here, so please correct that for
> > me.
> >
> >
> > The concept here is that groups are user-relative too (see below for
> > groups
> > discussion).  My group "family" is much different from your group
> > "family".
> > friends is really exactly this type of group.
> >
> >
> > >
> > >
> > >
> > > >
> > > > /people/{uid}/all/{pid}      -- Individual person record.
> > >
> > >
> > > Sounds like: "Get people for user, {uid}; All of them. Only with
> person
> > > id,
> > > {pid}."
> > >
> > > Why not drop the 'all'? /people/{uid}/{pid}
> >
> >
> > I only put the "all" in there to make the URLs less confusing --
> anything
> > at
> > level 3 is always a person-id, anything at level 2 is always a group id.
> > Conceptually you're saying "give me the person record as accessed
> through
> > group 'X'".  Today people records are the same no matter what group
> you're
> > in, but I could imagine wanting to change this (e.g., having a
> > date-added-to-group field) which might vary depending on the context.
> >
> >
> >
> > >
> > >
> > > Then it could sound like, "Get people for user, {uid}; with person id,
> > > {pid}."
> > > Sounds like: "Get people for user, {uid}, with person id {pid}."
> > >
> > >
> > > > /people/{uid}/sel            -- Self Profile record for user {uid}
> > >
> > >
> > > Sounds like, "Get people for user, {uid}; sel."
> > >
> > > Why not drop the 'sel' here, and /people/{uid}/ just refers to that
> user
> > > resource specified by {uid}.
> >
> >
> > We could probably drop @self (we added @ signs to make meta-names not
> > conflict with regular names).  Thoughts?
> >
> >
> > >
> > >
> > >
> > > > /groups/{uid}/self           -- Collection of groups owned by the
> > > > user, which always contains 'all' and 'friends' and may contain
> more.
> > > > (Details TBD)
> > > >
> > > >
> > > Sounds like: "Get groups for user, {uid}; self."
> > > Perhaps, predicated on the group definition, it could just be
> > > /groups/{uid}
> > > which gets all groups that user, {uid} belongs (owns?) to.
> >
> >
> > The intended semantics are groups the user owns.  If we drop @self then
> it
> > would just be /groups/{uid}
> >
> >
> > >
> > >
> > > What is group ownership? Is the group any subset of people that a user
> > > knows?
> > >
> >
> > A user can in principle set up any number of groups to classify the
> people
> > they know.  They get one special group by default, "friends".  Not
> > everybody
> > they know is necessarily a friend.
> >
> > This is different from groups-you-belong-to in principle, in that you
> can
> > set up a group and stuff me in it without me being aware of it or
> caring.
> > (Again, "friends" is special and has additional semantics -- it's double
> > opt
> > in.  Other groups may have special semantics too, but the API doesn't
> > specify those semantics.)
> >
>

Re: semantics of the restful server url templates

[Vasu Nori <vn...@google.com>]

Let me summarize People Restful API and the IMPLIED data model behind it.

API calls

   - /people/{uid}/all - Collection of all Public profiles for all users
   connected with uid {uid}


   - /people/{uid}/friends        -- Collection of all Public profiles
   for all users connected with user {uid} and group = "friends"
   - /people/{uid}/{groupid}      -- Collection of all people connected
   to user {uid} in group {groupid}
   - /people/{uid}/@all/{pid}      -- Public profile, returning ALL
   attributes of the user {pid} which are visible to ANY of the groups of user
   {uid}
   - /people/{uid}/@self            -- Return the COMPLETE Profile for
   user {uid}
   - /groups/{uid}/@self   -  Return ALL groups for user {uid}


Data Model (in the following, Level N+1 is inside Level N object)

   - *Level_1 * Person Object
   - *Level_2 * uid  String type
      - *Level_2 * set of all groups for this user
         - *Level_3  *groupid  (Reserved words: family, friends)
      - *Level_3 * for each group, contacts
            - *Level_4 * set of all contacts of in this group
            (set of Person objects identified by their uid)


   - *Level_2 * User profile attributes
         - *Level_3 * for each attribute, flag = public/private
         - *Level_3 * for each attribute, indicate which of the
         user's groups can view this attribute
            - *Level_4 *set of groups this attribute belongs to

what do you say?

On Wed, Apr 16, 2008 at 12:07 PM, John Panzer <jp...@google.com> wrote:

> On Tue, Apr 15, 2008 at 4:43 PM, Robert Evans <bo...@google.com> wrote:
>
> > I am trying to think of the URIs as mapping to resources on the web, and
> > trying to read it out loud. Consequently, please see the reading of URIs
> > and
> > some questions/suggestions interspersed below.
> >
> > Thanks,
> > Bob
> >
> > On Mon, Apr 14, 2008 at 10:02 PM, David Primmer <david.primmer@gmail.com
> >
> > wrote:
> >
> > > We're struggling with these implementation details right now. I'd love
> > > to see what others have decided on.
> > >
> > > quick summary of the proposed url system (just for the people api)
> > >
> > > /people/{uid}/all            -- Collection of all people connected to
> > user
> > > {uid}
> >
> >
> > Sounds like: "Get people for user, {uid}; all of them."
>
>
> Yes (of course, it really just names the group of all people connected to
> user {uid}, you can do GET/PUT/POST/DELETE on this collection depending on
> what you want to do).
>
>
> >
> >
> > >
> > > /people/{uid}/friends        -- Collection of all friends of user
> {uid};
> > > subset of all
> >
> >
> >  Sounds like: "Get people for user, {uid}; only those who are friends."
>
>
> Yep.
>
>
> >
> >
> > >
> > > /people/{uid}/{groupid}      -- Collection of all people connected to
> > user
> > > {uid} in group {groupid}
> >
> >
> > Sounds like: "Get people for user, {uid}; who are also in group_id."
> >
> > That one is confusing. Won't this be the same as all people in {group
> id}?
> > I
> > have only a vague concept of "group" here, so please correct that for
> me.
>
>
> The concept here is that groups are user-relative too (see below for
> groups
> discussion).  My group "family" is much different from your group
> "family".
> friends is really exactly this type of group.
>
>
> >
> >
> >
> > >
> > > /people/{uid}/all/{pid}      -- Individual person record.
> >
> >
> > Sounds like: "Get people for user, {uid}; All of them. Only with person
> > id,
> > {pid}."
> >
> > Why not drop the 'all'? /people/{uid}/{pid}
>
>
> I only put the "all" in there to make the URLs less confusing -- anything
> at
> level 3 is always a person-id, anything at level 2 is always a group id.
> Conceptually you're saying "give me the person record as accessed through
> group 'X'".  Today people records are the same no matter what group you're
> in, but I could imagine wanting to change this (e.g., having a
> date-added-to-group field) which might vary depending on the context.
>
>
>
> >
> >
> > Then it could sound like, "Get people for user, {uid}; with person id,
> > {pid}."
> > Sounds like: "Get people for user, {uid}, with person id {pid}."
> >
> >
> > > /people/{uid}/sel            -- Self Profile record for user {uid}
> >
> >
> > Sounds like, "Get people for user, {uid}; sel."
> >
> > Why not drop the 'sel' here, and /people/{uid}/ just refers to that user
> > resource specified by {uid}.
>
>
> We could probably drop @self (we added @ signs to make meta-names not
> conflict with regular names).  Thoughts?
>
>
> >
> >
> >
> > > /groups/{uid}/self           -- Collection of groups owned by the
> > > user, which always contains 'all' and 'friends' and may contain more.
> > > (Details TBD)
> > >
> > >
> > Sounds like: "Get groups for user, {uid}; self."
> > Perhaps, predicated on the group definition, it could just be
> > /groups/{uid}
> > which gets all groups that user, {uid} belongs (owns?) to.
>
>
> The intended semantics are groups the user owns.  If we drop @self then it
> would just be /groups/{uid}
>
>
> >
> >
> > What is group ownership? Is the group any subset of people that a user
> > knows?
> >
>
> A user can in principle set up any number of groups to classify the people
> they know.  They get one special group by default, "friends".  Not
> everybody
> they know is necessarily a friend.
>
> This is different from groups-you-belong-to in principle, in that you can
> set up a group and stuff me in it without me being aware of it or caring.
> (Again, "friends" is special and has additional semantics -- it's double
> opt
> in.  Other groups may have special semantics too, but the API doesn't
> specify those semantics.)
>

Re: semantics of the restful server url templates

[John Panzer <jp...@google.com>]

On Tue, Apr 15, 2008 at 4:43 PM, Robert Evans <bo...@google.com> wrote:

> I am trying to think of the URIs as mapping to resources on the web, and
> trying to read it out loud. Consequently, please see the reading of URIs
> and
> some questions/suggestions interspersed below.
>
> Thanks,
> Bob
>
> On Mon, Apr 14, 2008 at 10:02 PM, David Primmer <da...@gmail.com>
> wrote:
>
> > We're struggling with these implementation details right now. I'd love
> > to see what others have decided on.
> >
> > quick summary of the proposed url system (just for the people api)
> >
> > /people/{uid}/all            -- Collection of all people connected to
> user
> > {uid}
>
>
> Sounds like: "Get people for user, {uid}; all of them."


Yes (of course, it really just names the group of all people connected to
user {uid}, you can do GET/PUT/POST/DELETE on this collection depending on
what you want to do).


>
>
> >
> > /people/{uid}/friends        -- Collection of all friends of user {uid};
> > subset of all
>
>
>  Sounds like: "Get people for user, {uid}; only those who are friends."


Yep.


>
>
> >
> > /people/{uid}/{groupid}      -- Collection of all people connected to
> user
> > {uid} in group {groupid}
>
>
> Sounds like: "Get people for user, {uid}; who are also in group_id."
>
> That one is confusing. Won't this be the same as all people in {group id}?
> I
> have only a vague concept of "group" here, so please correct that for me.


The concept here is that groups are user-relative too (see below for groups
discussion).  My group "family" is much different from your group "family".
friends is really exactly this type of group.


>
>
>
> >
> > /people/{uid}/all/{pid}      -- Individual person record.
>
>
> Sounds like: "Get people for user, {uid}; All of them. Only with person
> id,
> {pid}."
>
> Why not drop the 'all'? /people/{uid}/{pid}


I only put the "all" in there to make the URLs less confusing -- anything at
level 3 is always a person-id, anything at level 2 is always a group id.
Conceptually you're saying "give me the person record as accessed through
group 'X'".  Today people records are the same no matter what group you're
in, but I could imagine wanting to change this (e.g., having a
date-added-to-group field) which might vary depending on the context.



>
>
> Then it could sound like, "Get people for user, {uid}; with person id,
> {pid}."
> Sounds like: "Get people for user, {uid}, with person id {pid}."
>
>
> > /people/{uid}/sel            -- Self Profile record for user {uid}
>
>
> Sounds like, "Get people for user, {uid}; sel."
>
> Why not drop the 'sel' here, and /people/{uid}/ just refers to that user
> resource specified by {uid}.


We could probably drop @self (we added @ signs to make meta-names not
conflict with regular names).  Thoughts?


>
>
>
> > /groups/{uid}/self           -- Collection of groups owned by the
> > user, which always contains 'all' and 'friends' and may contain more.
> > (Details TBD)
> >
> >
> Sounds like: "Get groups for user, {uid}; self."
> Perhaps, predicated on the group definition, it could just be
> /groups/{uid}
> which gets all groups that user, {uid} belongs (owns?) to.


The intended semantics are groups the user owns.  If we drop @self then it
would just be /groups/{uid}


>
>
> What is group ownership? Is the group any subset of people that a user
> knows?
>

A user can in principle set up any number of groups to classify the people
they know.  They get one special group by default, "friends".  Not everybody
they know is necessarily a friend.

This is different from groups-you-belong-to in principle, in that you can
set up a group and stuff me in it without me being aware of it or caring.
(Again, "friends" is special and has additional semantics -- it's double opt
in.  Other groups may have special semantics too, but the API doesn't
specify those semantics.)

Re: semantics of the restful server url templates

[Robert Evans <bo...@google.com>]

I am trying to think of the URIs as mapping to resources on the web, and
trying to read it out loud. Consequently, please see the reading of URIs and
some questions/suggestions interspersed below.

Thanks,
Bob

On Mon, Apr 14, 2008 at 10:02 PM, David Primmer <da...@gmail.com>
wrote:

> We're struggling with these implementation details right now. I'd love
> to see what others have decided on.
>
> quick summary of the proposed url system (just for the people api)
>
> /people/{uid}/all            -- Collection of all people connected to user
> {uid}


Sounds like: "Get people for user, {uid}; all of them."

>
> /people/{uid}/friends        -- Collection of all friends of user {uid};
> subset of all


 Sounds like: "Get people for user, {uid}; only those who are friends."

>
> /people/{uid}/{groupid}      -- Collection of all people connected to user
> {uid} in group {groupid}


Sounds like: "Get people for user, {uid}; who are also in group_id."

That one is confusing. Won't this be the same as all people in {group id}? I
have only a vague concept of "group" here, so please correct that for me.


>
> /people/{uid}/all/{pid}      -- Individual person record.


Sounds like: "Get people for user, {uid}; All of them. Only with person id,
{pid}."

Why not drop the 'all'? /people/{uid}/{pid}

Then it could sound like, "Get people for user, {uid}; with person id,
{pid}."
Sounds like: "Get people for user, {uid}, with person id {pid}."


> /people/{uid}/sel            -- Self Profile record for user {uid}


Sounds like, "Get people for user, {uid}; sel."

Why not drop the 'sel' here, and /people/{uid}/ just refers to that user
resource specified by {uid}.


> /groups/{uid}/self           -- Collection of groups owned by the
> user, which always contains 'all' and 'friends' and may contain more.
> (Details TBD)
>
>
Sounds like: "Get groups for user, {uid}; self."
Perhaps, predicated on the group definition, it could just be /groups/{uid}
which gets all groups that user, {uid} belongs (owns?) to.

What is group ownership? Is the group any subset of people that a user
knows?