Updated osapi and data pipelining in Core-Gadget

[Lane, 2009-12-11 05:31:00]

Hi Jon,

I'd like you to do a review of these changes.  In cleaning up osapi and Data
Pipelining, I added a couple types to Core-Data.xml so that osapi.http and
os:HttpRequest can share request parameters and response types for making
requests to artitrary URLs.

Thanks,
Lane

[Lane, 2009-12-11 05:31:24]

Hi Jon,

I'd like you to do a review of these changes.  In cleaning up osapi and Data
Pipelining, I added a couple types to Core-Data.xml so that osapi.http and
os:HttpRequest can share request parameters and response types for making
requests to artitrary URLs.

Thanks,
Lane

[Jon Weygandt, 2009-12-11 18:27:55]

http://codereview.appspot.com/174057/diff/1/3
File Core-Data.xml (right):

http://codereview.appspot.com/174057/diff/1/3#newcode286
Core-Data.xml:286: </section>
In general I have tried to alphabetize the sections and parameters in the
section. That would need to be done.

http://codereview.appspot.com/174057/diff/1/3#newcode296
Core-Data.xml:296: <c>params</c>
params did not exist in v0.9 docs, "body", which seems like params was in
examples, but not in the official params for the methods.

http://codereview.appspot.com/174057/diff/1/2
File Core-Gadget.xml (right):

http://codereview.appspot.com/174057/diff/1/2#newcode2317
Core-Gadget.xml:2317: <t>The services available on the client are determined by
the server from
This paragraph and example should go under the new section
"osapi.<service-name>", see comments below.

http://codereview.appspot.com/174057/diff/1/2#newcode2333
Core-Gadget.xml:2333: <section title="Service Requests">
Note: There seem to be 3 major objects: Request (a base class), derived classes
"osapi.<service-request>" and BatchRequest. The comments below are intended to
get that across.

http://codereview.appspot.com/174057/diff/1/2#newcode2342
Core-Gadget.xml:2342: <t
hangText="Signature">osapi.&lt;service-name&gt;.&lt;method-name&gt;.execute(callback)</t>
I believe this signature would simply be "osapi.Request.execute(callback)". The
service and method would be used to create one of these. 
OR
You are missing the (params) argument after <method-name>

http://codereview.appspot.com/174057/diff/1/2#newcode2351
Core-Gadget.xml:2351: <c>A callback function to handle the response. The
callback function will be invoked with a parameter which contains the payload
specified by the service method that is invoked.</c>
will be invoked with a parameter which contains the >>response<< payload
specified...

http://codereview.appspot.com/174057/diff/1/2#newcode2370
Core-Gadget.xml:2370: </section>
Add a new section:
12.14.1.X osapi.<service-name>

Services are made available through specific the osapi.Request objects. The
<service-name> is dependent upon the application, for example Social appliations
they are: people, activities, appdata, etc...

-- add in here the text about testing for the service (last part of 12.14) --

12.14.1.X.1 osapi.<service-name>.<method-name>

Signature
     <static> Type: { osapi.Request } osapi.<service-name>.<method-name>(params)

Description
    Builds a request to retreive information from the server. This request may
be executed immediatly by the osapi.Request.execute(), or by batching them using
osapi.BatchRequest. The params are specific to the type of service and are
documented with the specific services.

http://codereview.appspot.com/174057/diff/1/2#newcode2437
Core-Gadget.xml:2437: <c>A callback function to handle the response. The
callback function will be invoked with a parameter which contains the payload
specified by the service method that is invoked.</c>
will be invoked with a parameter which contains a map. The key is the "key"
specified in the add method. The value is the response payload for the service.

http://codereview.appspot.com/174057/diff/1/2#newcode2548
Core-Gadget.xml:2548: is not a JSON-RPC endpoint, but a third party web
service.</t>
Add: The object created is an osapi.Request object, suitable for immediate
execution with osapi.Request.execute() or batch operations with
osapi.BatchRequest.

http://codereview.appspot.com/174057/diff/1/2#newcode2707
Core-Gadget.xml:2707: 'body': {'numResults': 100, theme: 'beach'},
body is not part of HTTP-Request-Params

http://codereview.appspot.com/174057/diff/1/2#newcode2723
Core-Gadget.xml:2723: <t>Tags that invoke API Server methods a 1:1 mapping
between the XML
Tags that invoke API Server methods >>support<< a 1:1

http://codereview.appspot.com/174057/diff/1/2#newcode2772
Core-Gadget.xml:2772: <t hangText="Returns">A JSON object representing the <eref
target="Core-Data.xml#Return-Object">Return-Object</eref> specified by the
service method.</t>
Missing the definition of Return-Object

[Lane, 2009-12-11 19:38:46]

Thanks for the great review, Jon.  Let me know what you think of my treatment of
osapi "Service Objects"

-Lane

http://codereview.appspot.com/174057/diff/1/3
File Core-Data.xml (right):

http://codereview.appspot.com/174057/diff/1/3#newcode286
Core-Data.xml:286: </section>
On 2009/12/11 18:27:55, Jon Weygandt wrote:
> In general I have tried to alphabetize the sections and parameters in the
> section. That would need to be done.

Done.

http://codereview.appspot.com/174057/diff/1/3#newcode296
Core-Data.xml:296: <c>params</c>
On 2009/12/11 18:27:55, Jon Weygandt wrote:
> params did not exist in v0.9 docs, "body", which seems like params was in
> examples, but not in the official params for the methods.

'params' is from HttpRequest
(http://www.opensocial.org/Technical-Resources/opensocial-spec-v09/OpenSocial-...)

You're right though, looks like osapi.http.put and osapi.http.post use body
(http://www.opensocial.org/Technical-Resources/opensocial-spec-v09/OpenSocial-...)

I've taken 'params' out of this object (since you could just include them in
href), and added the concept as a 'body' parameters in the osapi.http.post and
osapi.http.put and HttpRequest docs.

http://codereview.appspot.com/174057/diff/1/2
File Core-Gadget.xml (right):

http://codereview.appspot.com/174057/diff/1/2#newcode2317
Core-Gadget.xml:2317: <t>The services available on the client are determined by
the server from
On 2009/12/11 18:27:55, Jon Weygandt wrote:
> This paragraph and example should go under the new section
> "osapi.<service-name>", see comments below.

Done.

http://codereview.appspot.com/174057/diff/1/2#newcode2333
Core-Gadget.xml:2333: <section title="Service Requests">
On 2009/12/11 18:27:55, Jon Weygandt wrote:
> Note: There seem to be 3 major objects: Request (a base class), derived
classes
> "osapi.<service-request>" and BatchRequest. The comments below are intended to
> get that across.

Done.

http://codereview.appspot.com/174057/diff/1/2#newcode2342
Core-Gadget.xml:2342: <t
hangText="Signature">osapi.&lt;service-name&gt;.&lt;method-name&gt;.execute(callback)</t>
On 2009/12/11 18:27:55, Jon Weygandt wrote:
> I believe this signature would simply be "osapi.Request.execute(callback)".
The
> service and method would be used to create one of these. 
> OR
> You are missing the (params) argument after <method-name>

You're right on both...I went with osapi.Request.execute() as the signature

http://codereview.appspot.com/174057/diff/1/2#newcode2351
Core-Gadget.xml:2351: <c>A callback function to handle the response. The
callback function will be invoked with a parameter which contains the payload
specified by the service method that is invoked.</c>
On 2009/12/11 18:27:55, Jon Weygandt wrote:
> will be invoked with a parameter which contains the >>response<< payload
> specified...

Done.

http://codereview.appspot.com/174057/diff/1/2#newcode2370
Core-Gadget.xml:2370: </section>
On 2009/12/11 18:27:55, Jon Weygandt wrote:
> Add a new section:
> 12.14.1.X osapi.<service-name>
> 
> Services are made available through specific the osapi.Request objects. The
> <service-name> is dependent upon the application, for example Social
appliations
> they are: people, activities, appdata, etc...
> 
> -- add in here the text about testing for the service (last part of 12.14) --
> 
> 12.14.1.X.1 osapi.<service-name>.<method-name>
> 
> Signature
>      <static> Type: { osapi.Request }
osapi.<service-name>.<method-name>(params)
> 
> Description
>     Builds a request to retreive information from the server. This request may
> be executed immediatly by the osapi.Request.execute(), or by batching them
using
> osapi.BatchRequest. The params are specific to the type of service and are
> documented with the specific services.

I condensed this into a single "Service Objects" section. Let me know what you
think.

http://codereview.appspot.com/174057/diff/1/2#newcode2437
Core-Gadget.xml:2437: <c>A callback function to handle the response. The
callback function will be invoked with a parameter which contains the payload
specified by the service method that is invoked.</c>
On 2009/12/11 18:27:55, Jon Weygandt wrote:
> will be invoked with a parameter which contains a map. The key is the "key"
> specified in the add method. The value is the response payload for the
service.
> 

Done.

http://codereview.appspot.com/174057/diff/1/2#newcode2548
Core-Gadget.xml:2548: is not a JSON-RPC endpoint, but a third party web
service.</t>
On 2009/12/11 18:27:55, Jon Weygandt wrote:
> Add: The object created is an osapi.Request object, suitable for immediate
> execution with osapi.Request.execute() or batch operations with
> osapi.BatchRequest.

Done.

http://codereview.appspot.com/174057/diff/1/2#newcode2707
Core-Gadget.xml:2707: 'body': {'numResults': 100, theme: 'beach'},
On 2009/12/11 18:27:55, Jon Weygandt wrote:
> body is not part of HTTP-Request-Params

I think this is okay with my new comments in the osapi.http.post parameters
section

http://codereview.appspot.com/174057/diff/1/2#newcode2723
Core-Gadget.xml:2723: <t>Tags that invoke API Server methods a 1:1 mapping
between the XML
On 2009/12/11 18:27:55, Jon Weygandt wrote:
> Tags that invoke API Server methods >>support<< a 1:1

Done.

http://codereview.appspot.com/174057/diff/1/2#newcode2772
Core-Gadget.xml:2772: <t hangText="Returns">A JSON object representing the <eref
target="Core-Data.xml#Return-Object">Return-Object</eref> specified by the
service method.</t>
On 2009/12/11 18:27:55, Jon Weygandt wrote:
> Missing the definition of Return-Object

Whoops..that should be Core-API-Server.xml#Return-Object.  Fixed

[Jon Weygandt, 2009-12-11 21:17:34]

+1

http://codereview.appspot.com/174057/diff/2003/9
File Core-Gadget.xml (right):

http://codereview.appspot.com/174057/diff/2003/9#newcode2317
Core-Gadget.xml:2317: <section title="Service Objects">
I like this!

[Lane, 2009-12-11 21:46:11]

Cool...it's committed and preview available at:

http://www.opensocial.org/Technical-Resources/draft/Core-Gadget.xml
http://www.opensocial.org/Technical-Resources/draft/Core-Data.xml

Cheers,
Lane

On Fri, Dec 11, 2009 at 1:17 PM, <jon.weygandt@gmail.com> wrote:

> +1
>
>
> http://codereview.appspot.com/174057/diff/2003/9
> File Core-Gadget.xml (right):
>
> http://codereview.appspot.com/174057/diff/2003/9#newcode2317
> Core-Gadget.xml:2317: <section title="Service Objects">
> I like this!
>
> http://codereview.appspot.com/174057
>
> --
>
> 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-and-gadgets-spec@googlegroups.com.
> To unsubscribe from this group, send email to
>
opensocial-and-gadgets-spec+unsubscribe@googlegroups.com<opensocial-and-gadge...
> .
> For more options, visit this group at
> http://groups.google.com/group/opensocial-and-gadgets-spec?hl=en.
>
>
>