Hey John, Chris has now asked the same questions I've asked previously (i think it was on the spec list tho?)
Anyhow, any chance that you can just cut and paste your explanations from this thread into the spec? I know it's not a perfectly worded spec language but it really is better than nothing. You say "It says representation, not 'complete representation' :)." And while one may be able to figure this out, if they really tried, it still begs more questions and it's better just to elaborate on those questions right there and just be done with it. I'd say error on the side of being more pedagogical. davep On Mon, Jul 14, 2008 at 4:32 PM, John Panzer <[EMAIL PROTECTED]> wrote: > 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.) >>> >> >> >
