Re: Align OpenSocial and Poco in fields definitions in v 1.0 (issue152119)

[api.ll...@gmail.com]

Thanks for digging into all these details! I think there are a few
high-level issues we need to iron out...

1) Make sure to work with Jon Weygandt and make sure the changes to the
data model make it into the Social-Data.xml spec.

2a) A request for a single object, should get a single object (without
fields like itemsPerPage, etc). The way you changed the text makes all
requests return a collection.

2b) A request for a collection should get a collection (even if there's
just one item in it). The current spec says we should return a single
object (instead of an array) and add fields like itemsPerPage, etc. I'm
proposing we change/fix this.

3) I'm not sure we can just change <person>, <activities>, etc. to
<entry>. Seems like I should get a clue about whether to parse the
<entry> as a person, activity, etc. This is not an issue for PoCo
since they only have one data type (i.e. person). Also, this would
change the XSD significantly as it currently refers to <person>,
<activity> etc.

-Lane



http://codereview.appspot.com/152119/diff/1/2
File draft/REST-API.xml (right):

http://codereview.appspot.com/152119/diff/1/2#newcode192
draft/REST-API.xml:192: <preamble>or, for those methods designed to
return only one item:</preamble>
This changes the intent of the spec. The example says if you request a
list, but there is only one result, entry will be a single object, not
an array. this seems wrong...we should always return a collection if a
collection is requested.

The text you have says that all methods return a collection, in that the
response will container fields like itemsPerPage. This doesn't make
sense for requests like getOnwer - where only a single object will ever
be returned.

http://codereview.appspot.com/152119/diff/1/2#newcode271
draft/REST-API.xml:271: &lt;entry
xmlns="http://ns.opensocial.org/2008/opensocial"&gt;
If I get this XML, how do I know to parse it as a person, activity, or
something else?

http://codereview.appspot.com/152119/diff/1/2#newcode1625
draft/REST-API.xml:1625: <section title="Singular Person Fields">
Please work with Jon Weygandt to make sure these changes make it into
the Social-Gadget.xml file.

http://codereview.appspot.com/152119

[Jacky]

Thanks for the review! The patch has been updated.