API Server Specs

[Lane, 2009-12-03 07:37:58]

Hey Folks,

The Core-API-Server spec is ready for some reviewers.  A lot of the content is
moved from the REST and RPC specs, but the ABNF stuff is all new , so please
take a close look.

The Social-API-Server spec is still in progress.  Lots of services to document
there :)

Cheers,
Lane

[Lane, 2009-12-03 07:39:05]

n.b. the HTML version is available here:
http://www.opensocial.org/Technical-Resources/draft/Core-API-Server.xml

On 2009/12/03 07:37:58, Lane wrote:
> Hey Folks,
> 
> The Core-API-Server spec is ready for some reviewers.  A lot of the content is
> moved from the REST and RPC specs, but the ABNF stuff is all new , so please
> take a close look.
> 
> The Social-API-Server spec is still in progress.  Lots of services to document
> there :)
> 
> Cheers,
> Lane

[Paul Lindner, 2009-12-03 11:24:10]

looks good  it's nice to see these common elements tied together.

[Mark W., 2009-12-04 00:52:59]

In the CORE-API-SERVER, the text reads (line 142): 
"The protocol defines Activity, Person, Group, and AppData resources. Most
operations consist of retrieving (GET), updating (PUT), creating (POST or PUT),
or destroying (DELETE) these resources. It also specifies an optional partial
update feature which avoids sending large resources over the wire to update just
one field."

Since these are social concepts, shouldn't this be in the SOCIAL-API-SERVER or
am I confused and wandering aimlessly looking for wood?

[Lane, 2009-12-04 02:38:43]

I've taken that line out...you're not wandering :)

On Thu, Dec 3, 2009 at 4:52 PM, <weitzelm.ibm@gmail.com> wrote:

> In the CORE-API-SERVER, the text reads (line 142):
> "The protocol defines Activity, Person, Group, and AppData resources.
> Most operations consist of retrieving (GET), updating (PUT), creating
> (POST or PUT), or destroying (DELETE) these resources. It also specifies
> an optional partial update feature which avoids sending large resources
> over the wire to update just one field."
>
> Since these are social concepts, shouldn't this be in the
> SOCIAL-API-SERVER or am I confused and wandering aimlessly looking for
> wood?
>
>
>
> http://codereview.appspot.com/163096
>

[Lane, 2009-12-09 01:09:11]

Hi Folks,

I just uploaded a new patch set with a completed draft of the Social-API-Server
spec.  There are lots are missing/wrong links right now so don't worry about
them, but the content is ready for your review.

Core: http://www.opensocial.org/Technical-Resources/draft/Core-API-Server.xml
Status:
http://www.opensocial.org/Technical-Resources/draft/Social-API-Server.xml

You can also view what's left of the REST spec (the RPC spec has been completely
assimilated...mwahahaha).  Most of the content has been moved to the
*-API-Server and *-Data specs, but there is some stuff left that I want to make
sure get's covered in the *-Data specs. 

http://www.opensocial.org/Technical-Resources/draft/REST-API.xml

If you have specific feedback it's best to use the code review tool and leave me
comments inline.  If you have general feedback that's fine too...just post it on
the list.

Thanks,
Lane

[Jacky Wang, 2009-12-09 13:09:18]

Thanks for your great effort!!

Just my 2 cents:
- for the JSON / XML / ATOM mapping part, we need to move it to Core-Data.xml,
which is modifying by Jon (cc'ed Jon in).
- for the xml schemas for person/activity/..., it might be great to be broke
down to small pieces.
- let's submit an alpha version after all the big changes are done - then we
could do the second iteration on small changes - there should be many small bugs
we need to fix, and the whole OpenSocial community could help a hand on
reviewing the draft.

Great Job, Lane!

Thanks,
- Jacky

http://codereview.appspot.com/163096/diff/3007/3011
File Core-API-Server.xml (right):

http://codereview.appspot.com/163096/diff/3007/3011#newcode351
Core-API-Server.xml:351: <list style="symbols">
You may like to replace the following part with:

    <texttable>
     <ttcol align="left">Json Query Object</ttcol>
     <ttcol align="left">URL Parameter</ttcol>
     <c>{ "field" : "value" }</c><c>field=value</c>
     <c>{ "field" : [1,2,3,4,5]}</c><c>field=1,2,3,4,5</c>
     <c>{ "field" : "12" }</c><c>field='12'</c>
     <c>{ "field" :
[identifier,anotheridentifier]}</c><c>field=identifier,anotheridentifier</c>
     <c>{ "field" : ["value","another value"]}</c><c>field=value,"another
value"</c>
     <c>{ "field" : ['value','another value']}</c><c>field=value,'another
value'</c>
     <c>{ "field" : { "nested" : "value" }}</c><c>field.nested=value</c>
     <c>{ "field" : [{ "nested1" : "value1" }, { "nested2" : "value2"
}]}</c><c>field(0).nested1=value1&amp;field(1).nested2=value2</c>
    </texttable>

http://codereview.appspot.com/163096/diff/3007/3011#newcode1817
Core-API-Server.xml:1817: &lt;xs:element name="isFiltered" type="xs:boolean"
/&gt;
filtered

http://codereview.appspot.com/163096/diff/3007/3011#newcode1818
Core-API-Server.xml:1818: &lt;xs:element name="isSorted" type="xs:boolean" /&gt;
sorted

http://codereview.appspot.com/163096/diff/3007/3011#newcode1819
Core-API-Server.xml:1819: &lt;xs:element name="isUpdatedSince" type="xs:boolean"
/&gt;
updatedSince

http://codereview.appspot.com/163096/diff/3007/3010
File Social-API-Server.xml (right):

http://codereview.appspot.com/163096/diff/3007/3010#newcode1406
Social-API-Server.xml:1406: &lt;xs:element minOccurs="0" name="nickname"
type="xs:string" /&gt;
add after:
&lt;xs:element minOccurs="0" name="note" type="xs:string" /&gt;

http://codereview.appspot.com/163096/diff/3007/3010#newcode1466
Social-API-Server.xml:1466: &lt;xs:element minOccurs="0" name="extendedAddress"
type="xs:string" /&gt;
remove

http://codereview.appspot.com/163096/diff/3007/3010#newcode1470
Social-API-Server.xml:1470: &lt;xs:element minOccurs="0" name="poBox"
type="xs:string" /&gt;
remove

http://codereview.appspot.com/163096/diff/3007/3010#newcode1492
Social-API-Server.xml:1492: &lt;xs:element minOccurs="0" name="endDate"
type="xs:dateTime" /&gt;
add
&lt;xs:element minOccurs="0" name="location" type="xs:string" /&gt;

http://codereview.appspot.com/163096/diff/3007/3010#newcode1505
Social-API-Server.xml:1505: &lt;xs:element minOccurs="0" name="additionalName"
type="xs:string" /&gt;
remove

http://codereview.appspot.com/163096/diff/3007/3010#newcode1510
Social-API-Server.xml:1510: &lt;xs:element minOccurs="0" name="formatted"
type="xs:string" /&gt;
add
&lt;xs:element minOccurs="0" name="middleName" type="xs:string" /&gt;

http://codereview.appspot.com/163096/diff/3007/3010#newcode1732
Social-API-Server.xml:1732: &lt;/xs:schema&gt;
Still think that it might be a good way to break the above big xml down into
small pieces and insert them into the Social-Data.xml...

[Jacky Wang, 2009-12-09 13:25:34]

http://codereview.appspot.com/163096/diff/3007/3011
File Core-API-Server.xml (right):

http://codereview.appspot.com/163096/diff/3007/3011#newcode967
Core-API-Server.xml:967: <t>The actual content included in the response.</t>
As we've discussed in the Core-Data.xml part, the "core-data" only describes the
definition of "collection" and "entry", yet leave the discussion on "what should
be return, collection, entry, or error message" here.

Your point in group's thread is a good example actually:

==========
A Core API Server will always return a <response> element, which will have
one of three things in it:
1) an <entry> element, which could contain anything
2) a collection, which has a group of elements like <startIndex> and
<isSorted>, followed by a number of <entry> elements for the items in the
collection (or no <entry> elements if the collection is empty)
3) a <invalidationKeys> element, which contains at least one
<invalidationKey> element. 
==========

[Lane, 2009-12-09 18:08:59]

Thanks for the review Jacky!

http://codereview.appspot.com/163096/diff/3007/3011
File Core-API-Server.xml (right):

http://codereview.appspot.com/163096/diff/3007/3011#newcode351
Core-API-Server.xml:351: <list style="symbols">
On 2009/12/09 13:09:18, Jacky.Chao.Wang wrote:
> You may like to replace the following part with:
> 
>     <texttable>
>      <ttcol align="left">Json Query Object</ttcol>
>      <ttcol align="left">URL Parameter</ttcol>
>      <c>{ "field" : "value" }</c><c>field=value</c>
>      <c>{ "field" : [1,2,3,4,5]}</c><c>field=1,2,3,4,5</c>
>      <c>{ "field" : "12" }</c><c>field='12'</c>
>      <c>{ "field" :
> [identifier,anotheridentifier]}</c><c>field=identifier,anotheridentifier</c>
>      <c>{ "field" : ["value","another value"]}</c><c>field=value,"another
> value"</c>
>      <c>{ "field" : ['value','another value']}</c><c>field=value,'another
> value'</c>
>      <c>{ "field" : { "nested" : "value" }}</c><c>field.nested=value</c>
>      <c>{ "field" : [{ "nested1" : "value1" }, { "nested2" : "value2"
> }]}</c><c>field(0).nested1=value1&amp;field(1).nested2=value2</c>
>     </texttable>

Much better. Thanks!

http://codereview.appspot.com/163096/diff/3007/3011#newcode967
Core-API-Server.xml:967: <t>The actual content included in the response.</t>
On 2009/12/09 13:25:34, Jacky.Chao.Wang wrote:
> As we've discussed in the Core-Data.xml part, the "core-data" only describes
the
> definition of "collection" and "entry", yet leave the discussion on "what
should
> be return, collection, entry, or error message" here.
> 
> Your point in group's thread is a good example actually:
> 
> ==========
> A Core API Server will always return a <response> element, which will have
> one of three things in it:
> 1) an <entry> element, which could contain anything
> 2) a collection, which has a group of elements like <startIndex> and
> <isSorted>, followed by a number of <entry> elements for the items in the
> collection (or no <entry> elements if the collection is empty)
> 3) a <invalidationKeys> element, which contains at least one
> <invalidationKey> element. 
> ==========
> 

This is covered by the individual server, which defines the Return-Object for
each method.  For example, Social-API-Server.xml#People-Service-GetPerson
defines Return-Object = Person.  I'e added some text to clarify this.

However, this doesn't account for the root <response> tags, so I've added that
to Core-API-Server.xml#REST-Response.

Similarly, Core-API-Server.xml#RPC-Response defines the root response structure
in JSON (e.g. { "id" : "myrequest", "result" : <Some-Object> }

http://codereview.appspot.com/163096/diff/3007/3011#newcode1817
Core-API-Server.xml:1817: &lt;xs:element name="isFiltered" type="xs:boolean"
/&gt;
On 2009/12/09 13:09:18, Jacky.Chao.Wang wrote:
> filtered

Done.

http://codereview.appspot.com/163096/diff/3007/3011#newcode1818
Core-API-Server.xml:1818: &lt;xs:element name="isSorted" type="xs:boolean" /&gt;
On 2009/12/09 13:09:18, Jacky.Chao.Wang wrote:
> sorted

Done.

http://codereview.appspot.com/163096/diff/3007/3011#newcode1819
Core-API-Server.xml:1819: &lt;xs:element name="isUpdatedSince" type="xs:boolean"
/&gt;
On 2009/12/09 13:09:18, Jacky.Chao.Wang wrote:
> updatedSince

Done.

http://codereview.appspot.com/163096/diff/3007/3010
File Social-API-Server.xml (right):

http://codereview.appspot.com/163096/diff/3007/3010#newcode1406
Social-API-Server.xml:1406: &lt;xs:element minOccurs="0" name="nickname"
type="xs:string" /&gt;
On 2009/12/09 13:09:18, Jacky.Chao.Wang wrote:
> add after:
> &lt;xs:element minOccurs="0" name="note" type="xs:string" /&gt;

Done.

http://codereview.appspot.com/163096/diff/3007/3010#newcode1466
Social-API-Server.xml:1466: &lt;xs:element minOccurs="0" name="extendedAddress"
type="xs:string" /&gt;
On 2009/12/09 13:09:18, Jacky.Chao.Wang wrote:
> remove

Done.

http://codereview.appspot.com/163096/diff/3007/3010#newcode1470
Social-API-Server.xml:1470: &lt;xs:element minOccurs="0" name="poBox"
type="xs:string" /&gt;
On 2009/12/09 13:09:18, Jacky.Chao.Wang wrote:
> remove

Done.

http://codereview.appspot.com/163096/diff/3007/3010#newcode1492
Social-API-Server.xml:1492: &lt;xs:element minOccurs="0" name="endDate"
type="xs:dateTime" /&gt;
On 2009/12/09 13:09:18, Jacky.Chao.Wang wrote:
> add
> &lt;xs:element minOccurs="0" name="location" type="xs:string" /&gt;

Done.

http://codereview.appspot.com/163096/diff/3007/3010#newcode1505
Social-API-Server.xml:1505: &lt;xs:element minOccurs="0" name="additionalName"
type="xs:string" /&gt;
On 2009/12/09 13:09:18, Jacky.Chao.Wang wrote:
> remove

Done.

http://codereview.appspot.com/163096/diff/3007/3010#newcode1510
Social-API-Server.xml:1510: &lt;xs:element minOccurs="0" name="formatted"
type="xs:string" /&gt;
On 2009/12/09 13:09:18, Jacky.Chao.Wang wrote:
> add
> &lt;xs:element minOccurs="0" name="middleName" type="xs:string" /&gt;

Done.

http://codereview.appspot.com/163096/diff/3007/3010#newcode1732
Social-API-Server.xml:1732: &lt;/xs:schema&gt;
On 2009/12/09 13:09:18, Jacky.Chao.Wang wrote:
> Still think that it might be a good way to break the above big xml down into
> small pieces and insert them into the Social-Data.xml...

Agreed.  I'll work with Jon to make this happen.

[Lane, 2009-12-10 18:06:46]

Just uploaded a new patch with all the links fixed.  Pull out the fine-toothed
comb and let me know if you find any tangles.

Thanks,
Lane

[snoopdave, 2009-12-11 20:26:16]

In the Social API Server specification there are empty headings for creating
people and lists of fields. Those are not things that have been in previous
OpenSocial specifications, except as examples intended "to show how additional
operations that a container may want to support can be defined within this
framework" [1]

I don't think provisioning of new users and creating of friendships is really
something we want Gadget developers to do and even if we do want such a thing,
don't we have a lot to do to standardize the relationship creation flow,
relationship types, etc.?

I think we should strike these headings from the document:

4.1.4 Retrieve a list of deleted friends
4.1.5 Create a Person
4.1.6 Update a Person
4.1.7 Delete a Person
4.1.8 Create a list of Friends
4.1.9 Update a list of Friends
4.1.10 Delete a list of Friends

Am I off base here in saying the above are new capabilities and thus should not
be included in 1.0?

For groups we currently have these also empty headings:

4.2 Groups
4.2.1 Create a list of Groups
4.2.2 Retrieve a list of Groups
4.2.3 Update a list of Groups
4.2.4 Delete a list of Groups

We never had Group creation or update in any previous version of the specs (as
far as I know). So, when I propose the Group changes, I'll believe I will be
changing these headings to something more like this:

4.2 Groups
4.2.2 Retrieve a list of Groups
4.2.4 Retrieve a Groups

Sound OK?

- Dave


[1]
http://www.opensocial.org/Technical-Resources/opensocial-spec-v09/RPC-Protoco...

[Jacky Wang, 2009-12-12 11:51:49]

On 2009/12/11 20:26:16, snoopdave wrote:
> In the Social API Server specification there are empty headings for creating
> people and lists of fields. Those are not things that have been in previous
> OpenSocial specifications, except as examples intended "to show how additional
> operations that a container may want to support can be defined within this
> framework" [1]
> 
> I don't think provisioning of new users and creating of friendships is really
> something we want Gadget developers to do and even if we do want such a thing,
> don't we have a lot to do to standardize the relationship creation flow,
> relationship types, etc.?
> 
> I think we should strike these headings from the document:
> 
> 4.1.4 Retrieve a list of deleted friends
> 4.1.5 Create a Person
> 4.1.6 Update a Person
> 4.1.7 Delete a Person
> 4.1.8 Create a list of Friends
> 4.1.9 Update a list of Friends
> 4.1.10 Delete a list of Friends
> 
> Am I off base here in saying the above are new capabilities and thus should
not
> be included in 1.0?
> 
> For groups we currently have these also empty headings:
> 
> 4.2 Groups
> 4.2.1 Create a list of Groups
> 4.2.2 Retrieve a list of Groups
> 4.2.3 Update a list of Groups
> 4.2.4 Delete a list of Groups
> 
> We never had Group creation or update in any previous version of the specs (as
> far as I know). So, when I propose the Group changes, I'll believe I will be
> changing these headings to something more like this:
> 
> 4.2 Groups
> 4.2.2 Retrieve a list of Groups
> 4.2.4 Retrieve a Groups
> 
> Sound OK?
> 
> - Dave
> 
> 
> [1]
>
http://www.opensocial.org/Technical-Resources/opensocial-spec-v09/RPC-Protoco...

LGTM +1.  Thank you Lane!

[Jacky Wang, 2009-12-21 11:15:47]

Hi All,

Any updates? Have them been submitted? :D

Cheers,
- Jacky

On 2009/12/12 11:51:49, Jacky.Chao.Wang wrote:
> On 2009/12/11 20:26:16, snoopdave wrote:
> > In the Social API Server specification there are empty headings for creating
> > people and lists of fields. Those are not things that have been in previous
> > OpenSocial specifications, except as examples intended "to show how
additional
> > operations that a container may want to support can be defined within this
> > framework" [1]
> > 
> > I don't think provisioning of new users and creating of friendships is
really
> > something we want Gadget developers to do and even if we do want such a
thing,
> > don't we have a lot to do to standardize the relationship creation flow,
> > relationship types, etc.?
> > 
> > I think we should strike these headings from the document:
> > 
> > 4.1.4 Retrieve a list of deleted friends
> > 4.1.5 Create a Person
> > 4.1.6 Update a Person
> > 4.1.7 Delete a Person
> > 4.1.8 Create a list of Friends
> > 4.1.9 Update a list of Friends
> > 4.1.10 Delete a list of Friends
> > 
> > Am I off base here in saying the above are new capabilities and thus should
> not
> > be included in 1.0?
> > 
> > For groups we currently have these also empty headings:
> > 
> > 4.2 Groups
> > 4.2.1 Create a list of Groups
> > 4.2.2 Retrieve a list of Groups
> > 4.2.3 Update a list of Groups
> > 4.2.4 Delete a list of Groups
> > 
> > We never had Group creation or update in any previous version of the specs
(as
> > far as I know). So, when I propose the Group changes, I'll believe I will be
> > changing these headings to something more like this:
> > 
> > 4.2 Groups
> > 4.2.2 Retrieve a list of Groups
> > 4.2.4 Retrieve a Groups
> > 
> > Sound OK?
> > 
> > - Dave
> > 
> > 
> > [1]
> >
>
http://www.opensocial.org/Technical-Resources/opensocial-spec-v09/RPC-Protoco...
> 
> LGTM +1.  Thank you Lane!