Detailed feedback thread: 3-OpenSocial_0_8_REST_API_Spec.html

[Dan Peterson]

As per below, please use this thread to discuss potential improvements to the OpenSocial API RESTful spec (v0.8):
http://opensocial-and-gadgets-spec.googlegroups.com/web/3-OpenSocial_0_8_REST_API_Spec.html

Regards,
-Dan

---------- Forwarded message ----------
From: Dan Peterson <dpet...@google.com>
Date: Fri, May 9, 2008 at 6:27 PM
Subject: Ready for review: Complete drafts of OpenSocial v0.8 and related spec updates
To: opensocial-and-gadgets-spec <opensocial-an...@googlegroups.com>


Hi folks,

As discussed last week, the full draft of OpenSocial v0.8 specification is ready for your review. This draft specification includes updates to existing specs, inclusion of the RESTful spec, release notes, and detailed JavaScript doc (JSDoc). The intent was to clearly capture all of the 40+ changes/additions that we have developed on this mailing list since version 0.7 of the spec (as tracked in http://spreadsheets.google.com/pub?key=pigtmOB55Aw_YJHz040u0Kg&gid=0 ). Let's use the next week or two to make improvements to these docs and then we can lock down 0.8.

You can find all 6 of these documents uploaded into the "Files" section of this Google Group: http://groups.google.com/group/opensocial-and-gadgets-spec/files?&sort=name

The draft documents published are (please note that some of the links in the files might not work as this is only a staged copy):

• 1 - OpenSocial 0.8 Release Notes
• 2 - OpenSocial 0.8 Specification
• 3 - OpenSocial 0.8 RESTful API Specification
• 4 - gadgets Specification
• Canonical gadgets XSD
• Extended gadgets XSD
• gadgets Message Bundle XSD
  
• 5 - opensocial.* 0.8 JS doc
• 6 - gadgets.* JS doc

I have conveniently numbered these documents so it is easier for you to walk through them in a clear order. In addition, documents 1 through 4 have their additions/updates highlighted for ease of reference. To better organize detailed feedback for each document, I will now start a thread for each of the 6 documents. Please be sure to direct your feedback to the appropriate thread.

Also, as a reminder, this coming Wednesday, May 15, we'll be holding an OpenSocial Summit in Mountain View, California. This event is an ideal opportunity to discuss this draft specification, propose ideas for future iterations, and learn about the latest happenings in the community -- as well as get to know each other in person.

You can learn more about the event at: http://opensocialapis.blogspot.com/2008/05/opensocial-summit-may-14th-at.html
The agenda is here: https://docs.google.com/View?docID=dds2mvj3_1vxvsnzfd
(RSVP is here: http://spreadsheets.google.com/viewform?key=pKy6PfiaRD2NIEhpx692Oaw )

Looking forward to your feedback (in the appropriate thread ;),
-Dan

[Kevin Brown]

Might I propose that all opensocial-related specifications use this format? Even though there are some known issues with implementing the RESTful spec, there is very little ambiguity here and it's very easy to reference subsections of it. Right now, the gadget spec is wildly different (although slightly closer in format), and the primary opensocial spec is a different type of document altogether.

I consider myself pretty familiar with all aspects of the spec, but when I read it today I can't help but be confused, as my comments on the other threads indicated. The format used by the RESTful spec is a perfect example of how to do this right.

[David Glazer]

One general observation (that applies to all of Kevin's suggestions on all the threads) -- there are two sorts of comments being made here:

- ways we could tighten up all the spec documents, regardless of any content changes from 0.7 to 0.8

- ways we could better improve the substance and/or wording of the 0.8 changes

I think both are good sets of feedback; it might help the conversation to clearly highlight which are which.  Personally, I consider the second set to be the most urgent to agree on, since that's more blocking to people (shindig, containers) who already have 0.7 implementations and want to upgrade them.  But in the long run, the first set will end up being more important, since there will be many more new eyes than old over time.

  - dG

[Kevin Brown]

Could we replace the links to the RFC documents with the canonical IETF versions? Linking to versions on the OAuth site doesn't seem to make a lot of sense.

On Fri, May 9, 2008 at 6:33 PM, Dan Peterson <dpet...@google.com> wrote:

[Paul Walker]

2.2 Person

q

A Person contains a scoial network oriented data about a single person.

/q

 

How about:  A Person represents a user of the social network.

 

q

- The field names are the same as in the JS doc, but lowercased.

/q

 

Does this mean keeping the underscores?  Are we not using camel casing in order to be consistent w/ common practices of XML and JSON (including OpenSearch)?  Perhaps we should actually enumerate the fields in the doc with their exact spelling capitalization?

 

~Paul

[Paul Walker]

2.4 Activity

 

What about enforcing template ids as URIs? 

 

~Paul

[Paul Walker]

More 2.2…

 

q

atom:entry/atom:id aliases the "id" field.  In the Atom format, it is translated into the required URI data type by prepending "urn:guid:" to the OpenSocial ID string.

/q

 

That's not the only way to translate the id field into a valid URI.  The text reads as if OS Providers must use urn:guid.  Is that the case? 

 

q

atom:entry/atom:published aliases the JSON field indicating creation time (POSTED_TIME for Activity).

/q

 

The example atom instance does not contain this atom field.  Perhaps the text could be a little more clear on what atom fields are required/optional?

 

The example instance mixes two default namespaces.  Shouldn't one of them include a prefix?

 

<entry xmlns="http://www.w3.org/2005/Atom"

                xmlns:os="http://ns.opensocial.org/2008/opensocial">

  <content type="application/xml">

    <os:person >

      <os:name>

        <os:unstructured>Jane Doe</os:unstructured>

      </os:name>

      <os:gender key="FEMALE">??</os:gender>

    </os:person>

  </content>

  <title/>

  <updated>2003-12-13T18:30:02Z</updated>

  <author/>

  <id>urn:guid:example.org:34KJDCSKJN2HHF0DW20394</id>

</entry>

 

Applies to activity instance in 2.4 as well...

 

q

The atom:summary element is the appropriate place to put a text or HTML representation of the structured data present in the content element

/q

 

Perhaps some text on how the type attribute would be used for this?

[Paul Walker]

 

2.3 Group

 

What is the purpose of the link field in the examples?  Is this the actual REST API URI for this resource? 

 

q

Groups only appear within Group Collections and are used to retrieve a list of available groups for a given person.

/q

 

Will we not make a resource available to retrieve a single group which would return the collection of person entries?

 

[Kevin Brown]

On Wed, May 14, 2008 at 1:55 AM, Paul Walker <pwa...@myspace.com> wrote:

2.2 Person

q

A Person contains a scoial network oriented data about a single person.

/q

 

How about:  A Person represents a user of the social network.

 

q

- The field names are the same as in the JS doc, but lowercased.

/q

 

Does this mean keeping the underscores?  Are we not using camel casing in order to be consistent w/ common practices of XML and JSON (including OpenSearch)?  Perhaps we should actually enumerate the fields in the doc with their exact spelling capitalization?

Common conventions for most XML and JSON is to use camel casing. It's not clear to me why the lower casing is necessary at all. Why not simply use the same field names as the JS?

[Paul Lindner]

* Need Updates on Partial Updates which is marked TBD

On Fri, May 09, 2008 at 06:33:21PM -0700, Dan Peterson wrote:
> As per below, please use this thread to discuss potential improvements to
> the OpenSocial API RESTful spec (v0.8):
> http://opensocial-and-gadgets-spec.googlegroups.com/web/3-OpenSocial_0_8_REST_API_Spec.html
>
> Regards,
> -Dan
>

> From: Dan Peterson <dpet...@google.com>
> Date: Fri, May 9, 2008 at 6:27 PM
> Subject: Ready for review: Complete drafts of OpenSocial v0.8 and related
> spec updates
> To: opensocial-and-gadgets-spec <
> opensocial-an...@googlegroups.com>
>
>
> Hi folks,
>
> As discussed last week, the full draft of OpenSocial v0.8 specification is
> ready for your review. This draft specification includes updates to existing
> specs, inclusion of the RESTful spec, release notes, and detailed JavaScript
> doc (JSDoc). The intent was to clearly capture all of the 40+
> changes/additions that we have developed on this mailing list since version
> 0.7 of the spec (as tracked in
> http://spreadsheets.google.com/pub?key=pigtmOB55Aw_YJHz040u0Kg&gid=0 ).
> Let's use the next week or two to make improvements to these docs and then
> we can lock down 0.8.
>
> You can find all 6 of these documents uploaded into the "Files" section of
> this Google Group:
> http://groups.google.com/group/opensocial-and-gadgets-spec/files?&sort=name
>
> The draft documents published are (please note that some of the links in the
> files might not work as this is only a staged copy):
>

> - 1 - OpenSocial 0.8 Release Notes
> - 2 - OpenSocial 0.8 Specification
> - 3 - OpenSocial 0.8 RESTful API Specification
> - 4 - gadgets Specification
> - Canonical gadgets XSD
> - Extended gadgets XSD
> - gadgets Message Bundle XSD
> - 5 - opensocial.* 0.8 JS doc
> - 6 - gadgets.* JS doc

>
> I have conveniently numbered these documents so it is easier for you to walk
> through them in a clear order. In addition, documents 1 through 4 have their
> additions/updates highlighted for ease of reference. To better organize
> detailed feedback for each document, I will now start a thread for each of
> the 6 documents. Please be sure to direct your feedback to the appropriate
> thread.
>
> Also, as a reminder, this coming Wednesday, May 15, we'll be holding an
> OpenSocial Summit in Mountain View, California. This event is an ideal
> opportunity to discuss this draft specification, propose ideas for future
> iterations, and learn about the latest happenings in the community -- as
> well as get to know each other in person.
>
> You can learn more about the event at:
> http://opensocialapis.blogspot.com/2008/05/opensocial-summit-may-14th-at.html
> The agenda is here: https://docs.google.com/View?docID=dds2mvj3_1vxvsnzfd
> (RSVP is here:
> http://spreadsheets.google.com/viewform?key=pKy6PfiaRD2NIEhpx692Oaw )
>
> Looking forward to your feedback (in the appropriate thread ;),
> -Dan
>

> 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
> -~----------~----~----~----~------~----~------~--~---
>

--
Paul Lindner ||||| | | | | | | | | |
lin...@inuus.com

[Paul Walker]

Sorry for the confusion. The spec states:

* The field names are the same as in the JS documentation, but lowercased.

So that means the fields would be <about_me>, <job_interests>, etc which is not camel cased, but lower cased w/ underbars. Not a big deal, but I just wanted to point it out since I think it will make the xml instances look somewhat funky in my mind as the openSearch parameters will be camel cased.

~Paul

------

 
Does this mean keeping the underscores?  Are we not using camel casing in order to be consistent w/ common practices of XML and JSON (including OpenSearch)?  Perhaps we should actually enumerate the fields in the doc with their exact spelling capitalization?

Common conventions for most XML and JSON is to use camel casing. It's not clear to me why the lower casing is necessary at all. Why not simply use the same field names as the JS?
 
 

Hi folks,

* 1 - OpenSocial 0.8 Release Notes
* 2 - OpenSocial 0.8 Specification
* 3 - OpenSocial 0.8 RESTful API Specification
* 4 - gadgets Specification
o Canonical gadgets XSD
o Extended gadgets XSD
o gadgets Message Bundle XSD
* 5 - opensocial.* 0.8 JS doc
* 6 - gadgets.* JS doc

[John Panzer]

On Wed, May 14, 2008 at 1:55 AM, Paul Walker <pwa...@myspace.com> wrote:

2.2 Person

q

A Person contains a scoial network oriented data about a single person.

/q

 

How about:  A Person represents a user of the social network.

Problem:  The Person record may be about a person who is not a user of that social network.  I could for example have a group of "followed" people with data based only on what I've typed in; the RESTful API is kind of agnostic about this.

In the most common case of course the Person _does_ represent a user of the social network :).
 

 

q

- The field names are the same as in the JS doc, but lowercased.

/q

 

Does this mean keeping the underscores?  Are we not using camel casing in order to be consistent w/ common practices of XML and JSON (including OpenSearch)?  Perhaps we should actually enumerate the fields in the doc with their exact spelling capitalization?

Yes, we should, I'm just lazy (and wanted to make sure I didn't end up out of sync with 0.8). 

I'm very agnostic about underscores via camel case vs...  Given the conflicting conventions used in (for example) OpenSearch and OAuth, I don't think 100% consistency is even possible :)
 

[Paul Walker]

Supporting clients that can’t easily use PUT, DELETE, HEAD http verbs.

 

There’s somewhat of a standard out there to allow clients to override the http verb by supplying an X-HttpMethodOverride header in the request or to provide a _method query parameter on a POST request that is meant to be PUT, DELETE, HEAD, OPTIONS but the client is not capable of sending those verbs.

 

I think it makes sense for the spec to support this.

 

~Paul

[John Panzer]

+1 to X-HttpMethodOverride:  on a POST to simulate PUT/DELETE/HEAD/OPTIONS.

[John Panzer]

Asking around, there is some confusion about this, and it's also possible that we'd be more aligned with both the JS API and other standards using the same nomenclature if we used camelCase instead of underbar_separated.  The specific spec text change would be:

The field names are the same as in the JS documentation, but lowercased.

to

The field names are the same as in the JS documentation, in camelCase -- e.g., aboutMe.

I am somewhat agnostic about this but if we're going to change this, we should do it now :).  It would make some things (like OpenSearch parameters) align better.

[John Panzer]

Sorry, forgot the call to action:  Any objections to changing to camelCase for fields?

[John Panzer]

Unless there are objections, I'll add in a paragraph describing this to the spec.

[John Panzer]

On Wed, May 14, 2008 at 1:57 AM, Paul Walker <pwa...@myspace.com> wrote:

More 2.2…

 

q

atom:entry/atom:id aliases the "id" field.  In the Atom format, it is translated into the required URI data type by prepending "urn:guid:" to the OpenSocial ID string.

/q

 

That's not the only way to translate the id field into a valid URI.  The text reads as if OS Providers must use urn:guid.  Is that the case? 

Great point.  No, this should be changed.  Suggested spec wording change:

In the Atom format, it is translated into the required URI data type by prepending "urn:guid:" to the OpenSocial ID string.

to

In the Atom format, this is translated into a valid URI (required by the Atom specification).  If the OpenSocial ID string is already a GUID, the container MAY prepend the prefix "urn:guid:" to the OpenSocial ID string to obtain a valid URI.

Votes?
 

[John Panzer]

(Not sure what this means...?)

[David Primmer]

sounds good.

I should mention, just in case this isn't correctly implemented that
right now in the shindig server, for an atom activity entry's author
element, which has a similar rule to id, has a child uri element and
looks like this:

<author><uri>urn:guid:john.doe</uri></author>

the id element has no uri child however. is this correct?

davep

[John Panzer]

yup

[Paul Walker]

Cool, just a correction on my initial casing…sometimes I’m anal, it’s X-HTTPMethodOverride.

 

From: opensocial-an...@googlegroups.com [mailto:opensocial-an...@googlegroups.com] On Behalf Of John Panzer
Sent: Wednesday, May 21, 2008 6:46 PM
To: opensocial-an...@googlegroups.com
Subject: Re: Detailed feedback thread: 3-OpenSocial_0_8_REST_API_Spec.html

 

Unless there are objections, I'll add in a paragraph describing this to the spec.

[Paul Walker]

+1, No objection.  Although, we need to get some actual instances of the json/atom reps in the doc.

 

In general, the REST spec is all about the incoming requests and outgoing responses.  An enumeration of the various URIs and example request/responses would go a long way right now.

 

From: opensocial-an...@googlegroups.com [mailto:opensocial-an...@googlegroups.com] On Behalf Of John Panzer

Sent: Wednesday, May 21, 2008 6:46 PM

[Eiji Kitamura]

Hi,


Partial Updates part is still marked TBD on official spec
documentation.

http://code.google.com/apis/opensocial/docs/0.8/restfulspec.html

Is this really in state of TO BE DETERMINED?


Sorry if I'm just not reading required document.

On 5月14日, 午後6:59, Paul Lindner <lind...@inuus.com> wrote:
> * Need Updates on Partial Updates which is marked TBD
>
>
>
> On Fri, May 09, 2008 at 06:33:21PM -0700, Dan Peterson wrote:
> > As per below, please use this thread to discuss potential improvements to
> > the OpenSocial API RESTful spec (v0.8):

> >http://opensocial-and-gadgets-spec.googlegroups.com/web/3-OpenSocial_...
>
> > Regards,
> > -Dan

>
> > From: Dan Peterson <dpeter...@google.com>
> > Date: Fri, May 9, 2008 at 6:27 PM
> > Subject: Ready for review: Complete drafts of OpenSocial v0.8 and related
> > spec updates
> > To: opensocial-and-gadgets-spec <
> > opensocial-an...@googlegroups.com>
>
> > Hi folks,
>
> > As discussed last week, the full draft of OpenSocial v0.8 specification is
> > ready for your review. This draft specification includes updates to existing
> > specs, inclusion of the RESTful spec, release notes, and detailed JavaScript
> > doc (JSDoc). The intent was to clearly capture all of the 40+
> > changes/additions that we have developed on this mailing list since version
> > 0.7 of the spec (as tracked in
> >http://spreadsheets.google.com/pub?key=pigtmOB55Aw_YJHz040u0Kg&gid=0).
> > Let's use the next week or two to make improvements to these docs and then
> > we can lock down 0.8.
>
> > You can find all 6 of these documents uploaded into the "Files" section of
> > this Google Group:

> >http://groups.google.com/group/opensocial-and-gadgets-spec/files?&sor...

>
> > The draft documents published are (please note that some of the links in the
> > files might not work as this is only a staged copy):
>
> > - 1 - OpenSocial 0.8 Release Notes
> > - 2 - OpenSocial 0.8 Specification
> > - 3 - OpenSocial 0.8 RESTful API Specification
> > - 4 - gadgets Specification
> > - Canonical gadgets XSD
> > - Extended gadgets XSD
> > - gadgets Message Bundle XSD
> > - 5 - opensocial.* 0.8 JS doc
> > - 6 - gadgets.* JS doc
>
> > I have conveniently numbered these documents so it is easier for you to walk
> > through them in a clear order. In addition, documents 1 through 4 have their
> > additions/updates highlighted for ease of reference. To better organize
> > detailed feedback for each document, I will now start a thread for each of
> > the 6 documents. Please be sure to direct your feedback to the appropriate
> > thread.
>
> > Also, as a reminder, this coming Wednesday, May 15, we'll be holding an
> > OpenSocial Summit in Mountain View, California. This event is an ideal
> > opportunity to discuss this draft specification, propose ideas for future
> > iterations, and learn about the latest happenings in the community -- as
> > well as get to know each other in person.
>
> > You can learn more about the event at:

> >http://opensocialapis.blogspot.com/2008/05/opensocial-summit-may-14th...

> > The agenda is here:https://docs.google.com/View?docID=dds2mvj3_1vxvsnzfd
> > (RSVP is here:
> >http://spreadsheets.google.com/viewform?key=pKy6PfiaRD2NIEhpx692Oaw)
>
> > Looking forward to your feedback (in the appropriate thread ;),
> > -Dan
>
> > 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 athttp://groups.google.com/group/opensocial-and-gadgets-spec?hl=en
> > -~----------~----~----~----~------~----~------~--~---
>
> --
> Paul Lindner ||||| | | | | | | | | |
> lind...@inuus.com
>
> application_pgp-signature_part
> 1Kダウンロード