V3 Client

170 views
Skip to first unread message

Joe Gregorio

unread,
Jun 28, 2010, 5:10:21 PM6/28/10
to gdata-python-client-...@googlegroups.com
I've just checked in a prototype for a version 3.0 client into subversion:

http://code.google.com/p/gdata-python-client/source/browse/#svn/trunk/v3

!! This is a prototype and not production ready !!

At Google I/O we explained what we learned from building APIs at Google and how
we have taken that learning and rolled it into a new infrastructure
for building APIs.
The Buzz, Moderator and Latitude APIs are all built on that new infrastructure.

http://code.google.com/events/io/2010/sessions/how-google-builds-apis.html

One of the key pieces enabled by that new infrastructure is discovery,
a document
that describes each API. For example:

http://www.googleapis.com/discovery/0.1/describe?api=buzz&apiVersion=1&pp=1

That is a JSON document that describes the Buzz API, and you get similar
documents for Latitude and Moderator:

http://www.googleapis.com/discovery/0.1/describe?api=moderator&apiVersion=1&pp=1
http://www.googleapis.com/discovery/0.1/describe?api=latitude&apiVersion=1&pp=1

It is very early days for discovery, and that's reflected in the '0.1'
version number. Expect the
discovery document to change rapidly and in non-backward compatible ways.

One of the benefits of discovery is that it allows very lightweight
client libraries.
That's where this version 3 client comes in, it is built from the
ground up to use
discovery. Using httplib2, python-oath2, and the uri-templates
libraries, along with the discovery
document means that the actual code for the client is very small;
apiclient.py is less that 200 lines of code.

There is a design document for the direction I'd like to see the library take:

http://code.google.com/p/gdata-python-client/wiki/V3ClientDesign

You can look in the README file in the v3 directory for instructions on how to
run the current code.

I've released this very rough and early to get feedback as early as
possible, so
please let me know what you think.

Thanks,
-joe

pkeane

unread,
Jun 28, 2010, 11:59:28 PM6/28/10
to GData Python Client Library Contributors


On Jun 28, 4:10 pm, Joe Gregorio <j...@bitworking.org> wrote:
> I've just checked in a prototype for a version 3.0 client into subversion:
>
>    http://code.google.com/p/gdata-python-client/source/browse/#svn/trunk/v3
>
>   !! This is a prototype and not production ready !!
>
> At Google I/O we explained what we learned from building APIs at Google and how
> we have taken that learning and rolled it into a new infrastructure
> for building APIs.
> The Buzz, Moderator and Latitude APIs are all built on that new infrastructure.
>
>    http://code.google.com/events/io/2010/sessions/how-google-builds-apis...
>
> One of the key pieces enabled by that new infrastructure is discovery,
> a document
> that describes each API. For example:
>
>    http://www.googleapis.com/discovery/0.1/describe?api=buzz&apiVersion=...
>
> That is a JSON document that describes the Buzz API, and you get similar
> documents for Latitude and Moderator:
>
>    http://www.googleapis.com/discovery/0.1/describe?api=moderator&apiVer...
>    http://www.googleapis.com/discovery/0.1/describe?api=latitude&apiVers...
>

Might be nice to have a place to go (a meta-discovery document?) to
figure out which services offer this new style API. I'm also keen to
see discovery documents linked to from an HTML page (e.g., my google
buzz profile page would have head/link/@rel=service that would point
at the pertinent discovery doc).

--peter keane

Joe Gregorio

unread,
Jun 29, 2010, 5:11:09 PM6/29/10
to gdata-python-client-...@googlegroups.com
On Mon, Jun 28, 2010 at 11:59 PM, pkeane <pjk...@gmail.com> wrote:
>
>
> On Jun 28, 4:10 pm, Joe Gregorio <j...@bitworking.org> wrote:
>> I've just checked in a prototype for a version 3.0 client into subversion:
>>
>>    http://code.google.com/p/gdata-python-client/source/browse/#svn/trunk/v3
>>
>>   !! This is a prototype and not production ready !!
>>
>> At Google I/O we explained what we learned from building APIs at Google and how
>> we have taken that learning and rolled it into a new infrastructure
>> for building APIs.
>> The Buzz, Moderator and Latitude APIs are all built on that new infrastructure.
>>
>>    http://code.google.com/events/io/2010/sessions/how-google-builds-apis...
>>
>> One of the key pieces enabled by that new infrastructure is discovery,
>> a document
>> that describes each API. For example:
>>
>>    http://www.googleapis.com/discovery/0.1/describe?api=buzz&apiVersion=...
>>
>> That is a JSON document that describes the Buzz API, and you get similar
>> documents for Latitude and Moderator:
>>
>>    http://www.googleapis.com/discovery/0.1/describe?api=moderator&apiVer...
>>    http://www.googleapis.com/discovery/0.1/describe?api=latitude&apiVers...
>>
>
> Might be nice to have a place to go (a meta-discovery document?) to
> figure out which services offer this new style API.

There are two parts to that, discovering which services are available,
which is coming.

Then there is discovery for the discovery service, which is itself a
discovery based API:

http://www.googleapis.com/discovery/0.1/describe?api=discovery

That part is already done.

> I'm also keen to
> see discovery documents linked to from an HTML page (e.g., my google
> buzz profile page would have head/link/@rel=service that would point
> at the pertinent discovery doc).

That's an interesting idea, it might also make a good candidate
to add to our experimental WebFinger service.

Thanks,
-joe

pkeane

unread,
Jun 30, 2010, 4:09:19 PM6/30/10
to GData Python Client Library Contributors
I've been playing with the code and have an OK idea of what is going
on -- sample.py works in getting the title of my last Buzz entry. I
don't quite, though see how to POST a new entry. I suspect it is
something like:

resp = p.activities().insert(resource=resource,userId='@me')

But I cannot quite puzzle out from the code how to create that
resource (resource = '{"data":{"object":
{"type":"note","content":"trying out gdata client v3"}}}') did not
work.

Any chance of getting a short sample snippet for that operation? With
a couple of examples I think I'll be able to triangulate a bit a to
get my head around the new discovery (JSON/WADL?) approach.

Sorry if this is not the proper forum for my question!

--peter keane



On Jun 28, 4:10 pm, Joe Gregorio <j...@bitworking.org> wrote:
> I've just checked in a prototype for a version 3.0 client into subversion:
>
>    http://code.google.com/p/gdata-python-client/source/browse/#svn/trunk/v3
>
>   !! This is a prototype and not production ready !!
>
> At Google I/O we explained what we learned from building APIs at Google and how
> we have taken that learning and rolled it into a new infrastructure
> for building APIs.
> The Buzz, Moderator and Latitude APIs are all built on that new infrastructure.
>
>    http://code.google.com/events/io/2010/sessions/how-google-builds-apis...
>
> One of the key pieces enabled by that new infrastructure is discovery,
> a document
> that describes each API. For example:
>
>    http://www.googleapis.com/discovery/0.1/describe?api=buzz&apiVersion=...
>
> That is a JSON document that describes the Buzz API, and you get similar
> documents for Latitude and Moderator:
>
>    http://www.googleapis.com/discovery/0.1/describe?api=moderator&apiVer...
>    http://www.googleapis.com/discovery/0.1/describe?api=latitude&apiVers...

Joe Gregorio

unread,
Jun 30, 2010, 8:26:22 PM6/30/10
to gdata-python-client-...@googlegroups.com
On Wed, Jun 30, 2010 at 4:09 PM, pkeane <pjk...@gmail.com> wrote:
> I've been playing with the code and have an OK idea of what is going
> on -- sample.py works in getting the title of my last Buzz entry.  I
> don't quite, though see how to POST a new entry.

Ah, that would be a combination of several things. First, there's a
bug, line 154 should be:

return self._model.response(*self._http.request(url,
method=httpMethod, headers=headers, body=body))

If that line were correct you would pass the entity to send as the
'body' parameter
in the method call. You can see the 'body' parameter added to the methods
documentation in the design doc.

The other thing is that as of right now the discovery document doesn't provide
a schema for what the object to POST should look like. When it does
I expect to add _body() member functions, such as insert_body(), that
would return
an instantiated object of the right shape for passing into insert().
See the Model discussion in the design doc:

http://code.google.com/p/gdata-python-client/wiki/V3ClientDesign#Model


> I suspect it is something like:
>
> resp = p.activities().insert(resource=resource,userId='@me')
>
> But I cannot quite puzzle out from the code how to create that
> resource (resource = '{"data":{"object":
> {"type":"note","content":"trying out gdata client v3"}}}') did not
> work.
>
> Any chance of getting a short sample snippet for that operation?  With
> a couple of examples I think I'll be able to triangulate a bit a to
> get my head around the new discovery (JSON/WADL?) approach.
>
> Sorry if this is not the proper forum for my question!

This is the right forum for these questions.

Thanks,
-joe

> --
> You received this message because you are subscribed to the Google Groups "GData Python Client Library Contributors" group.
> To post to this group, send email to gdata-python-client-...@googlegroups.com.
> To unsubscribe from this group, send email to gdata-python-client-librar...@googlegroups.com.
> For more options, visit this group at http://groups.google.com/group/gdata-python-client-library-contributors?hl=en.
>
>

Peter Keane

unread,
Jun 30, 2010, 10:21:32 PM6/30/10
to gdata-python-client-...@googlegroups.com
Great - thanks! That worked (I'd been starting to feel dense). The
bug makes sense -- I was getting a "no Content-length" response from
the server that I just couldn't figure out how to fix.

Glad to hear about the discovery doc providing a prototype of the
resource -- that was a quite confusing aspect of this whole approach,
which is now making more sense.

Still need to wrap my head around the implications here -- JSON seems
perfect for such a WADLish approach. The biggest implication is that
this seems to remove the (otherwise quite necessary) reliance on
well-documented media types in a RESTful ecosystem. While (hopefully)
avoiding the tight bindings & other problems w/ SOAP/WS-*, etc.

--peter

Joe Gregorio

unread,
Jul 2, 2010, 1:46:08 PM7/2/10
to gdata-python-client-...@googlegroups.com
Thanks everyone for the feedback so far on the new design. I have updated the
specification to incorporate the feedback. I have also added in an example of
how to post a new item to the activities list using the current code.
Note that the example
doesn't reflect the intended long term design where you would call
p.activities().insert_body() to create a default body, and them modify
that body before passing it to insert().

You can see the changes to the spec here:

http://code.google.com/p/gdata-python-client/source/diff?spec=svn1003&old=993&r=1003&format=side&path=/wiki/V3ClientDesign.wiki

Thanks,
-joe

Joe Gregorio

unread,
Sep 17, 2010, 9:04:20 AM9/17/10
to gdata-python-client-...@googlegroups.com
What had been previously referred to as the v3 client has been moved out from the current project and into
its own project here:


There is also a new discussion group for that project:


   Thanks,
   -joe
Reply all
Reply to author
Forward
0 new messages