Clarifications about Person Service semantics

[Laurent-Walter Goix]

hello all,

i am looking for clarifications when interpreting the Person Service
specification in the Social API spec. from the spec, the GET retrieves
profile details about a single person or a list of persons.The "create
relationship", which is mentioned as POST (i believe this is correct),
is also quite clear.

but i become a bit confused about the semantics of the other verbs &
functionalities:
- the "update" is mentioned as POST (not PUT?). i can understand a
user can update his own information with it. what about POSTing /@me/
@friends. the current spec allows for only 1 person object to be
included, so should this be understood at modifying the information of
that friend only? i guess in this case this information is not his own
profile information but a "(modified) copy" of it, am i right?
- the "delete" is the most unclear statement to me. given the spec it
seems that this is used for cancelling the user's own information. is
this to be understood as cancelling the user account (DELETE /@me/
@self) ?

in this situation i couldn't find any hint in the spec to "delete a
relationship" (after i created one). at the same time, if the delete
is used to cancel one's own account, is there any dual "creation"
procedure supported?

i checked shindig's code as well but couldn't find any help as most of
these methods are not implemented.

thank you!
walter

[Evgeny Bogdanov]

I think it is a typo and should be PUT

I think the best is if create/delete creates user account and deletes it.

And for relationship there should be their own crud requests.

I believe, since creating an account and deleting it is normally processed by a platform

and there are no APIs for it, the relationships were added instead. If that's the case,

then delete should remove the relationship as opposed to create.

all things IMO

[Laurent-Walter Goix]

thank you evgeny for the clarification. should i submit an issue for
it or are they other opinions/feedbacks?

walter

[Laurent-Walter Goix]

hello evgeny, all,

summarizing, wouldn't it be easy to add some clarifying text in these
sections of the people service to
- clarify in section 2.1.2.1 that using group-id @self will actually
create the account (the user-id in the uri fragment or in the person
body may indicate a preferred requested user-id subject to server
policies), whilst any other value will create a relationship?
otherwise what is the meaning of such call?
- generalize the support for deletion in section 2.1.4 to any Group-Id
(not only @self), providing the same clarifications as above (@self
deletes the user account itself whilst any other group value deletes
the relationship). this would also link more easily with section
2.1.1.4 to retrieve "deleted" relationships

these little changes may clarify a lot the semantics of messages when
implementing. what are your thoughts?

walter

On Dec 21 2011, 10:37 am, Laurent-Walter Goix

[Evgeny Bogdanov]

I personally agree. The only thing I am not sure about is whether there is a need to create/delete account in API.

[Laurent-Walter Goix]

i just filed issue http://code.google.com/p/opensocial-resources/issues/detail?id=1233
to keep track of this discussion

[Evgeny Bogdanov]

To continue this discussion since it is connected to Person Service.

I submitted a patch with implementation to update Person service.

So there are few things to be clarified.

1. As Stanton asks concerning this REST API: http://opensocial-resources.googlecode.com/svn/spec/trunk/Social-API-Server.xml#People-Service-Update

"What's to stop one person from updating another person? The rest API says that the User-Id defaults to @me, but doesn't say you can't list another user. Shouldn't we only allow @me to be updated, which would be equivalent to the viewer id in the security token?"

Maybe User-Id should always be @me, so that user can only update his own information?

2. Also from Stanton: "I also don't see osapi.people.update() in the social gadget spec and if the intent is for it to be there, you should try to get the spec updated as well"

I believe it should added, no?

[Laurent-Walter Goix]

as i understand the API from a spec perspective, the update has
different meanings based on the the Group-Id (@self updates his own
info, whilst another group will update the corresponding person within
a list, such a friends or others)
but i do see it mostly used for "@me" user-id. i am also wondering the
meaning of it with another user-id, but maybe the original authors can
clarify this point?

i believe (as stanton suggested) it may have sense in some containers
based on delegation permissions, so i can authorize someone to update
my info, but of course i would suspect that not all containers (nor
all users) would allow this type of behaviour.

on the JS API point i'm no expert but maybe this was already answered
on the list.

walter

On Jan 23, 10:16 am, Evgeny Bogdanov <evgeny.bogda...@gmail.com>
wrote:

> To continue this discussion since it is connected to Person Service.
> I submitted a patch with implementation to update Person service.
> So there are few things to be clarified.
>

> 1. As Stanton asks concerning this REST API:http://opensocial-resources.googlecode.com/svn/spec/trunk/Social-API-...

[Evgeny Bogdanov]

I submitted a patch for this issue here.

http://code.google.com/p/opensocial-resources/issues/detail?id=1233&colspec=ID%20Type%20Container%20Stars%20Summary%20Status

There is one question left for me.

The REST/RPC apis have the following structure

= "/people/" User-Id "/" Group-Id

+

A Person object representing a targeted user

In other words, let's say, we use Update API

Logged in user (either authenticated into a system or via security token) is doing an update.

Then he can specify on behalf of which user the update is done (User-Id - User ID of the person initiating the update request.)

and which user is to be updated (Person object with an id field).

IMO, it's quite a complex structure and I believe User-Id should always equal "@me". But if it's always @me, then probably it's better to change User-Id into targeted user and not rely on Person object's id.

This would remove this third unnecessary concept and unify get/post/update/delete requests...

Note that in Get request User-Id is the list of user to be requested and not initiator of a request.

[Henry Saputra]

I think the container should be allowed to prevent update to other users if authenticated user is not allowed to make the change

--
You received this message because you are subscribed to the Google Groups "OpenSocial and Gadgets Specification Discussion" group.

To view this discussion on the web visit https://groups.google.com/d/msg/opensocial-and-gadgets-spec/-/4rf3RrK0nBIJ.

To post to this group, send email to opensocial-an...@googlegroups.com.
To unsubscribe from this group, send email to opensocial-and-gadg...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/opensocial-and-gadgets-spec?hl=en.

[Evgeny V. Bogdanov]

Yes, that's correct and this is the case at the moment.
It's up to the container whether an authenticated user can update info
of another user or not.

the problem is
1. there is an authenticated user
2. user on behalf of which the action (update/delete/create) is accomplished
3. target user where updates are sent to
All together, 3 people are involved, but should be 2

for example,
1. Alice - logged into container
2. She calls an api
PUT
= "/people/Bob/Group-Id"
with params: person = {id: "Carol", name: "New name"}
-> will assign new name to Carol

As spec says: Bob = User ID of the person initiating the update request
I believe, Bob should always match Alice (the initiator of update request) or be "@me"

IMO, the User ID should be an id of a person to be updated, like this:
1. Alice - logged into container
2. She calls an api
PUT
= "/people/Carol/Group-Id"
with params: person = {name: "New name"}
-> will assign new name to Carol

Pls check: http://opensocial-resources.googlecode.com/svn/spec/trunk/Social-API-Server.xml#People-Service-CreateRelationship
and
http://opensocial-resources.googlecode.com/svn/spec/trunk/Social-API-Server.xml#People-Service-Update

[Ryan Baxter]

Evgeny, I agree with what you are proposing below.  The user logged into the container and the user making the update should always be the same.

To post to this group, send email to opensocial-and-gadgets-spec@googlegroups.com.
To unsubscribe from this group, send email to opensocial-and-gadgets-spec+unsub...@googlegroups.com.

For more options, visit this group at http://groups.google.com/group/opensocial-and-gadgets-spec?hl=en.

--
You received this message because you are subscribed to the Google Groups "OpenSocial and Gadgets Specification Discussion" group.

To post to this group, send email to opensocial-and-gadgets-spec@googlegroups.com.
To unsubscribe from this group, send email to opensocial-and-gadgets-spec+unsub...@googlegroups.com.

[Mark W.]

This is actually a pretty interesting discussion... In general I agree. However, we've been looking at a "run as" type of option on our REST APIs. One use case that comes up is a automated service that runs on behalf of a user. Has anyone else hit this type of scenario? 

[Ryan Baxter]

Can't say we (IBM) have...do you want to elaborate on the use case for this?

[James M Snell]

In such cases, using @me with an oauth token granted to the agent running on the users behalf would likely be the most appropriate.

To view this discussion on the web visit https://groups.google.com/d/msg/opensocial-and-gadgets-spec/-/9KQBz_y1sBoJ.
To post to this group, send email to opensocial-an...@googlegroups.com.
To unsubscribe from this group, send email to opensocial-and-gadg...@googlegroups.com.

[Mark W.]

Ryan,

The use case is pretty straightforward--I've got some backend service (e.g. at the most basic a cron job) that through business logic determines that an activity needs to be posted, or a profile updated, etc. (new level achieved in gamification engine, some BPM process, whatever...) 

James,

Using an OAuth token is an interesting idea and one we are looking at. I'd like to be able to make this work, but our current APIs are not protected by OAuth, so there's work to be done.  

To unsubscribe from this group, send email to opensocial-and-gadgets-spec+unsubs...@googlegroups.com.

For more options, visit this group at http://groups.google.com/group/opensocial-and-gadgets-spec?hl=en.

--
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+unsubs...@googlegroups.com.

For more options, visit this group at http://groups.google.com/group/opensocial-and-gadgets-spec?hl=en.

--
You received this message because you are subscribed to the Google Groups "OpenSocial and Gadgets Specification Discussion" group.
To view this discussion on the web visit https://groups.google.com/d/msg/opensocial-and-gadgets-spec/-/9KQBz_y1sBoJ.

[Laura Kolker [AppFusions]]

I'd like to +1 Mark's use case.

I'm a developer with AppFusions, and we do a lot of integration work with different technologies. The fundamental question with an integration that has to be addressed at the beginning is: does the integration use a service account that can do operations on the behalf of another user? There tend to be pluses and minuses to all of the approaches we've worked with. A service user has the benefit/negative of clearly being identified as a bot, so no one's confused about how the operation came to be, but also it makes the integration appear less seamless. As a developer in these contexts, we're rarely offered the opportunity to express what we would prefer: it's almost always more a matter of what do the APIs allow.  

Generally speaking, I find the service account approach (vs some kind of user mapping through OAuth or related) to be simpler to conceptualize and for the users to interact with re: configuration, so its definitely a feature I find extremely useful where its available. 

Laura

To post to this group, send email to opensocial-an...@googlegroups.com.
To unsubscribe from this group, send email to opensocial-and-gadg...@googlegroups.com.

For more options, visit this group at http://groups.google.com/group/opensocial-and-gadgets-spec?hl=en.

--
You received this message because you are subscribed to the Google Groups "OpenSocial and Gadgets Specification Discussion" group.

To post to this group, send email to opensocial-an...@googlegroups.com.
To unsubscribe from this group, send email to opensocial-and-gadg...@googlegroups.com.

For more options, visit this group at http://groups.google.com/group/opensocial-and-gadgets-spec?hl=en.

--
You received this message because you are subscribed to the Google Groups "OpenSocial and Gadgets Specification Discussion" group.
To view this discussion on the web visit https://groups.google.com/d/msg/opensocial-and-gadgets-spec/-/9KQBz_y1sBoJ.

To post to this group, send email to opensocial-an...@googlegroups.com.
To unsubscribe from this group, send email to opensocial-and-gadg...@googlegroups.com.

[Ryan Baxter]

Mark this sounds similar to an activity stream use case where a service, such as a tasks management service, posts to certain users activities streams about actions a separate user took in the app.

IE Super Task Service posts that Jane and Johns activity streams that I have closed their tasks.

This makes sense to me for activities but I am not sure I like a service being able to modify peoples profiles....but maybe we should allow for it if container choose to support this.

On Tuesday, June 12, 2012 7:09:34 AM UTC-4, Mark W. wrote:

[Mark W.]

Yeah, I kinda agree, but.... for every use case where we don't like it, we could probably think of one where we do. For example, what if your gamification engine wants to add a new badge to your profile? 

I get what Laura is saying about the "run as" model--it's one we've been looking at. Although I also like the idea of OAuth & scopes (what James has been talking about). This might be a way to allow some service update ONLY the badge. 

[James M Snell]

On Thu, Jun 14, 2012 at 4:54 AM, Mark W. <weitze...@gmail.com> wrote:

Yeah, I kinda agree, but.... for every use case where we don't like it, we could probably think of one where we do. For example, what if your gamification engine wants to add a new badge to your profile? 

There are better ways of achieving this without requiring direct edit access to a profile. For instance, via an Activity Service...

  POST /api/activities HTTP/1.1

  Host: example.org

  Content-Type: application/json

  {

    "actor": {"displayName": "gamification service"},

    "verb": "give",

    "object": {"objectType": "badge", "displayName": "You did it!"},

    "target": {"objectType": "person", "displayName": "Joe"}

  }

The server receiving this can then do the right thing in response. I would imagine that most third party "edit" scenarios could fall into similar patterns without requiring direct edit access.

 

I get what Laura is saying about the "run as" model--it's one we've been looking at. Although I also like the idea of OAuth & scopes (what James has been talking about). This might be a way to allow some service update ONLY the badge. 

When I think of "run as" I generally think more about automated profile maintenance or analysis operations.

 

To view this discussion on the web visit https://groups.google.com/d/msg/opensocial-and-gadgets-spec/-/VZvPDto8zVIJ.

To post to this group, send email to opensocial-an...@googlegroups.com.
To unsubscribe from this group, send email to opensocial-and-gadg...@googlegroups.com.

[Ryan Baxter]

James are you saying that when the server receives that activity it would also update the badge?

To view this discussion on the web visit https://groups.google.com/d/msg/opensocial-and-gadgets-spec/-/VZvPDto8zVIJ.

To view this discussion on the web visit https://groups.google.com/d/msg/opensocial-and-gadgets-spec/-/VZvPDto8zVIJ.

To view this discussion on the web visit https://groups.google.com/d/msg/opensocial-and-gadgets-spec/-/VZvPDto8zVIJ.

[James M Snell]

I'm saying that it's possible to use activities in a way that allows the server to respond in particular ways when specific activities occur.. So, yes, that's exactly what i'm saying.

To view this discussion on the web visit https://groups.google.com/d/msg/opensocial-and-gadgets-spec/-/88v9a4ppDHoJ.
To post to this group, send email to opensocial-an...@googlegroups.com.
To unsubscribe from this group, send email to opensocial-and-gadg...@googlegroups.com.