Updating OS Lite (osapi) portion of the spec

This update converts the content of the wiki page at http://wiki.opensocial.org/index.php?title=OSAPI_Specification to the new spec format.

I've also included a few updates based on Adam's comments on this thread: http://groups.google.com/group/opensocial-and-gadgets-spec/browse_thread/thread/1fc34b7d9e765f09/294b1aac49563baf?lnk=gst&q=os+lite#294b1aac49563baf

[Lane, 2009-04-03 20:13:41]

Incorporated Scott and Adam's feedback

[Lane, 2009-04-04 04:57:06]

Added some examples and <eref> tags to where the parameters are defined

[Lane, 2009-04-04 21:01:32]

Reformatted osapi reference to be more like the other API references

[Lane, 2009-04-04 21:02:31]

On 2009/04/04 21:01:32, api.lliabraa wrote:
> Reformatted osapi reference to be more like the other API references

I also changed a bunch of hard tabs to spaces.

[awiner, 2009-04-06 17:31:45]

Some significant comments on the HttpRequest section.  All else looked good.

http://codereview.appspot.com/33058/diff/1011/1013
File draft/Opensocial-Specification.xml (right):

http://codereview.appspot.com/33058/diff/1011/1013#newcode1265
Line 1265: gadgets.io.AuthorizationType AUTHORIZATION,
I believe this API should avoid references to gadgets.io, and simply refer to
constants (as this is JSON, and should be used accordingly).

Also, the constants are wrong.  In these cases, the appropriate constants should
all be exact clones of:

http://opensocial-resources.googlecode.com/svn/spec/draft/OpenSocial-Data-Pip...

... not gadgets.io.makeRequest(), and should follow the camelCasePattern
established there, not UPPERCASE_WITH_UNDERSCORES.

So, for example, href, not url.  contentType, not CONTENT_TYPE. 
refreshInterval, not REFRESH_INTERVAL.

http://codereview.appspot.com/33058/diff/1011/1013#newcode1271
Line 1271: Map.<String, String> HEADERS,
headers is Map<String, Array<String>>

http://codereview.appspot.com/33058/diff/1011/1013#newcode1275
Line 1275: String POST_DATA,
"head" doesn't have POST_DATA

http://codereview.appspot.com/33058/diff/1011/1013#newcode1280
Line 1280: <c>Takes an optional parameter that is a JSON object containing <eref
target="./Gadgets-API-Specification.xml#gadgets.io.RequestParameters">gadgets.io.RequestParameters</eref>.</c>
don't think gadgets.io.RequestParameters figures into this.

http://codereview.appspot.com/33058/diff/1011/1013#newcode1327
Line 1327: String POST_DATA,
"get" doesn't have post data.

http://codereview.appspot.com/33058/diff/1011/1013#newcode1431
Line 1431: String POST_DATA,
recommend calling this just "body", not POST_DATA.  It's for both PUT and POST,
so "POST" is too specific, and it's called "body" elsewhere.

http://codereview.appspot.com/33058/diff/1011/1013#newcode1521
Line 1521: 'AUTHORIZATION': 'SIGNED',
should be:
{
  href: 'http://www.somephotosite.com/latestphotos',
  authz: "signed",
  contentType: "text/json",  (not TEXT)
  headers: {"Content-Type": ["application/atom+xml"], "Accept-Language":
["en-us"]},
  post: "{myString: \"test\", myNumber: 123456}",
  refreshInterval: 3600
};

http://codereview.appspot.com/33058/diff/1011/1013#newcode1527
Line 1527: osapi.http.get('http://www.somephotosite.com/latestphotos',
params).execute(function(result) {
osapi.http.get(params).execute(...

[Evan Gilbert (code review), 2009-04-06 19:24:32]

http://codereview.appspot.com/33058/diff/1011/1013
File draft/Opensocial-Specification.xml (left):

http://codereview.appspot.com/33058/diff/1011/1013#oldcode810
Line 810: <section title="osapi.messages">
Any reason we've removed this?
http://opensocial-resources.googlecode.com/svn/spec/draft/RPC-Protocol.xml#rf...
has a clear spec for this. Think we should support either osapi.messages.send()
or requestSend()

http://codereview.appspot.com/33058/diff/1011/1013#oldcode830
Line 830: <t>osapi.ui.requestShareApp() - If the container allows the request to
process, the container will send a sharing message to the users or groups
represented in the "recipients" field, or prompt the viewer for recipients if
not provided.
Think it might make sense to keep osapi.ui.requestShareApp() and
requestPermission(). If we don't have these, then we lose functionality from
opensocial.* and have to include both libraries for almost all apps, which
increases latency and also means that we probably can't deprecate opensocial.*
in the 1.0 time frame, as you need at least one spec revision with an
alternative API.

http://codereview.appspot.com/33058/diff/1011/1013
File draft/Opensocial-Specification.xml (right):

http://codereview.appspot.com/33058/diff/1011/1013#newcode744
Line 744: <section title="getViewerFriends"
anchor="osapi.people.getViewerFriends">
Think that getViewerFriends() and getOwnerFriends() aren't needed, for a couple
of reasons:
- Justification for getViewer()/getOwner() is different return type.
osapi.people.get() normally returns a list.
- Friends will likely be one of many useful groups over time.

I'm OK if we decide to leave them in but have a prefrence for removing.

http://codereview.appspot.com/33058/diff/1011/1013#newcode1327
Line 1327: String POST_DATA,
On 2009/04/06 17:31:45, awiner wrote:
> "get" doesn't have post data.

User should have a way of passing in URL parameters as JSON. I.e.
osapi.http.get('http://www.site.com', {userId: '123'}). This can be either by
passing through unknown parameters or having both a "params" and a
"requestParams" argument.

http://codereview.appspot.com/33058/diff/1011/1013#newcode1543
Line 1543: &lt;static&gt; osapi.Request.execute(callback)
Preference for send() or call() here.

http://codereview.appspot.com/33058/diff/1011/1013#newcode1629
Line 1629: <section title="execute" anchor="osapi.BatchRequest.execute">
(also preference for send() or call())

[Lane, 2009-04-06 22:09:59]

Added osapi.messages and fixed parameters/examples for osapi.http.  Added
anchors to pipelining spec