John Panzer (http://abstractioneer.org)
On Mon, Jul 14, 2008 at 4:15 PM, Chris Chabot <[EMAIL PROTECTED]> wrote:
> No wonder i was confused.
>
> Section 6.1 says:
> "Friends may be added by POSTing to the appropriate collection (e.g.,
> /people/{guid}/@friends). Containers MAY require a dual opt-in process
> before the friend record appears in the collection, and in this case SHOULD
> return a 202 Accepted response, indicating that the request is 'in flight'
> and may or may not be ultimately successful."
>
> While in the batching example this is adding a friend:
> POST /people/@me/@all HTTP/1.1
> Host: api.example.org
> Content-Type: application/json
>
> ...representation of new Person elided...
>
> So to add a friend you do a ....
>
> POST to /people/{guid}/@friends
> OR
> POST to /people/@me/@all
>
> Which is it? Both? Neither? Pick one and pray it works? :)
Typo! Since you're adding a friend specifically, it should be @friends.
(The {guid}/@me is just a red herring here. Though if you're a third party
server trusted to add friends willy-nilly, you can do this.)
>
> Besides, the 'representation of a new Person', would insinuate a complete
> person object representation, not an Person ID of a person you want to
> befriend ... right? Why would you want to post a complete person
> representation to make a friend, that makes no sense to me (a waste of
> bandwidth and require an extra round trip in some situations), when just an
> ID would suffice? And if the latter is correct (just the ID) what
> representation would be correct for that?
It says representation, not 'complete representation' :). The idea is to
cover the existing functionality offered by things like social networks (at
least) by letting the client supply the best information it has:
1. If you have the ID, use it.
2. If you have another unique key, like email, use that.
3. If you have something else, like IM address, use that.
4. If you have some combination of data that's sufficiently unique, or may
be, give it a shot.
In cases where you have an unambiguous identifier (ID, email address, etc.)
then you use it. A container can also let you try to add a friend given
sufficient information (city, organization, and name for example might work
for some SNs; obviously this is getting into container-specific territory
but the syntax is uniform).
But to get back to brass tacks, if you have the ID somehow then you just
supply it: {"id" : "example.org:34KJDCSKJN2HHF0DW20394"}. The container
accepts that representation of a Person and hands back to you either a
fuller representation when you ask for it (GET) or it tells you 'wait a bit,
let me see if this is ok' with a 202.
>
>
> -- Chris
>
>
> On Jul 15, 2008, at 12:24 AM, John Panzer wrote:
>
> There's a spec diff proposal floating around on opensocial-and-gadgethat I
>> think explains the intent here: "Clarification on RESTful People API,
>> connections vs. contact records, and invitation workflow" (thread
>>
>> http://groups.google.com/group/opensocial-and-gadgets-spec/browse_thread/thread/2d542afdaf412c04
>> ).
>> The example above was about how to make a link to a person, or start the
>> workflow to make a link, not about how to create a new account in the SN.
>> (Which actually would be an interesting operation to define, particularly
>> for sites which have trusted partners who want to provision new accounts,
>> but it's clearly a P2 spec feature.)
>>
>
>
