Updated osapi and data pipelining in Core-Gadget (issue174057)

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

Reviewers: Jon Weygandt,

Message:
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



Please review this at http://codereview.appspot.com/174057

Affected files:
M Core-Data.xml
M Core-Gadget.xml

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

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

http://codereview.appspot.com/174057

[jon.we...@gmail.com]

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

http://codereview.appspot.com/174057

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

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-Data-Pipelining.html#HttpRequest)

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-Specification.html#osapi.http)

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

http://codereview.appspot.com/174057

[jon.we...@gmail.com]

+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

[Lane LiaBraaten]

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

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