[dart-announce] New Google APIs Client Libraries for Dart help Dart apps use Google services

['Anders Sandholm' via Dart Announcements]

[from http://news.dartlang.org/2014/09/new-google-apis-client-libraries-for.html]

We are always working on providing new APIs for Dart. If you have been using Google services from Dart, we are happy to say that the Dart Team is now supporting a client library for accessing a set of APIs to Google services.

Most Google services have an API described by the Google Discovery Service. This includes both Apps APIs (such as Gmail and Drive) and Cloud APIs (such as Cloud Datastore and Cloud Storage).

Based on previous work by GDEs Adam Singer and Gerwin Sturm, the Dart Team has built an API generator to create Dart client libraries enabling access to Google services. We recently published the following two packages on pub.dartlang.org:

 googleapis

 googleapis_beta

The googleapis package contains all the APIs that are available in a stable version. The googleapis_beta package contains the APIs that are currently in beta and possible only available through a Limited Preview program. We will be updating these packages on a monthly basis to ensure that they provide access to new services as they become available.

Along with the generated APIs, we have published a googleapis_auth package that handles all the different authorization models supported to access the APIs from different environments. Using googleapis_auth makes it easy to use the client libraries in a standalone application, on a Google Compute Engine instance, or in the browser.

To get started using the libraries, take a look at the GitHub repository googleapis_examples. The examples cover both Dart code that runs in the browser and Dart code that runs as a standalone program, demonstrating how to access Google Drive and Google Cloud Storage.

Please post on our discussion group if you have questions or comments on the client libraries. You can also file bugs on GitHub projects for the generator and the googleapis_auth package.

By Søren Gjesse, Software Engineer on Dart

--

Anders Thorhauge Sandholm,

Product Manager, Google Denmark

CVR nr. 28 86 69 84

--
For more news and information, visit https://plus.google.com/+dartlang
 
To join the conversation, visit https://groups.google.com/a/dartlang.org/

[Günter Zöchbauer]

These packages are great!

I wonder why there is no support for accessing the Datastore using Protobuf in addition to JSON?

There is another community package available that seems to do just that but I haven't tried it yet.

['Søren Gjesse' via Dart Announcements]

Right now these packages are generated from the discovery documents, which all support JSON defined by the JSON schema in these documents. The discovery document for Cloud Datastore v1beta2 as the only one of these APIs indicate support for protobuf response through the following information:

        "alt": {

            "default": "proto",

            "description": "Data format for the response.",

            "enum": [

                "json",

                "proto"

            ],

            "enumDescriptions": [

                "Responses with Content-Type of application/json",

                "Responses with Content-Type of application/x-protobuf"

            ],

            "location": "query",

            "type": "string"

        },

we might add support for protobuf bodies, but it raise an issue about the generated API, as it will have to take different request/response objects - the ones generated from the associated protobuf definition file.

Regards,

Søren

[Natalie Weizenbaum]

How are these packages going to be versioned?

For other discussions, see https://groups.google.com/a/dartlang.org/
 
For HOWTO questions, visit http://stackoverflow.com/tags/dart
 
To file a bug report or feature request, go to http://www.dartbug.com/new

To unsubscribe from this group and stop receiving emails from it, send an email to misc+uns...@dartlang.org.

[Søren Gjesse]

We are going to re-generate these on a regular basis. Each time they are re-generates we will check for breaking changes, and bump the version accordingly. This has the downside that one volatile API can cause the the package version to rise fast. However I think the benefit of having all APIs in one package outweighs this. 

When we have had some feedback and some rounds we will raise the version number to 1.0.0 and start counting.

The reason for the potential breaking changes is that even though the APIs in the googleapis package are released as stable they are not set in stone, and undergo changes pretty frequently - changes that might cause breaking changes in the generated Dart code. 

Regards,

Søren

[Bob Nystrom]

On Mon, Sep 22, 2014 at 2:30 PM, 'Søren Gjesse' via Dart Announcements <anno...@dartlang.org> wrote:

However I think the benefit of having all APIs in one package outweighs this. 

Out of curiosity, what benefits do you find to having them all in one package? I tend to prefer smaller packages I can mix and match, but I'd like to know more about other viewpoints.

Cheers!

- bob

[alberto.ags]

Maybe for avoid version nightmare of different packages.

Cheers

[Søren Gjesse]

I like the idea that you have one-stop shopping for all Google APIs this way. All these APIs operate the same way, and when you start using one extending to the next one becomes much easier. Discoverability is just better - It provides a clear view of which APIs are available and in which versions. Publishing 65 packages with longer names is not convenient.

Also as APIs gets deprecated (this is especially the case for the googleapis_beta package) we can just remove them, and there are no "stale" API package sitting in pub.dartlang.org.

The main reasons for having to bump the version number is when one API changes its interface. In some cases these changes also lead to changes in the wire protocol - in which case switching to the new version might even be required.

Of cause this opens the issue when depending packages are also using one of these packages and you get a violation constraint. However, this can still happen when splitting into several packages if the same API is used.

Regards,

Søren

--
For more news and information, visit https://plus.google.com/+dartlang
 
To join the conversation, visit https://groups.google.com/a/dartlang.org/

To unsubscribe from this group and stop receiving emails from it, send an email to announce+u...@dartlang.org.

[Bob Nystrom]

On Tue, Sep 23, 2014 at 7:24 AM, 'Søren Gjesse' via Dart Misc <mi...@dartlang.org> wrote:

I like the idea that you have one-stop shopping for all Google APIs this way. All these APIs operate the same way, and when you start using one extending to the next one becomes much easier. Discoverability is just better - It provides a clear view of which APIs are available and in which versions.

Yeah, that makes sense. Though it does reiterate that we have more work to do on package discoverability in general. Unfortunately, we've never had the resources to work on that side of things. :(

 

Publishing 65 packages with longer names is not convenient.

This is a fair point, though I personally lean towards making package consumption more convenient than package publishing. If it's better for users to consume a bunch of small packages (not that I'm saying it necessarily is in this case), I'd be willing to make it more of a hassle to publish them to get that. Packages are consumed more frequently than they are produced.

 

Also as APIs gets deprecated (this is especially the case for the googleapis_beta package) we can just remove them, and there are no "stale" API package sitting in pub.dartlang.org.

There won't be a stale package, but there will still be old versions of the monolithic googleapis_beta package that contain those deprecated APIs.

 

The main reasons for having to bump the version number is when one API changes its interface. In some cases these changes also lead to changes in the wire protocol - in which case switching to the new version might even be required.

I think my main worry here is that you'll be stuck on a very fast-moving version treadmill. Now when any of the APIs makes a change, you have to bump the version and republish all of them. With 65 packages, you may find yourself at major version 4,328 before you know it.

Revving major versions frequently makes your package very hard for users to consume. Shared constraints are common, and a constraint on a package always excludes the next major version that hasn't been released yet (since it may break the package using it). When you rev major versions frequently, it means other packages using you get outdated quickly.

That in itself isn't a problem. Users will just keep using the older version of your package. Where it is a problem is when users have shared dependencies on packages that all depend on googleapis_beta. There's a good chance those two (or more) packages won't depend on the same major version (since the window of time where that was the latest version is small) and you'll end up with a constraint failure.

You can ask the analyzer folks how much pain that caused. :(

Of cause this opens the issue when depending packages are also using one of these packages and you get a violation constraint. However, this can still happen when splitting into several packages if the same API is used.

This is true, but the solver handles a large number of stable packages more easily than a small number of quickly changing ones. It's simpler to pick the latest version of a hundred packages than it is to try to determine which of a small set of packages it should start backtracking on.

Cheers!

- bob

[Søren Gjesse]

On Tue, Sep 23, 2014 at 6:27 PM, 'Bob Nystrom' via Dart Misc <mi...@dartlang.org> wrote:

On Tue, Sep 23, 2014 at 7:24 AM, 'Søren Gjesse' via Dart Misc <mi...@dartlang.org> wrote:

I like the idea that you have one-stop shopping for all Google APIs this way. All these APIs operate the same way, and when you start using one extending to the next one becomes much easier. Discoverability is just better - It provides a clear view of which APIs are available and in which versions.

Yeah, that makes sense. Though it does reiterate that we have more work to do on package discoverability in general. Unfortunately, we've never had the resources to work on that side of things. :(

 

Publishing 65 packages with longer names is not convenient.

This is a fair point, though I personally lean towards making package consumption more convenient than package publishing. If it's better for users to consume a bunch of small packages (not that I'm saying it necessarily is in this case), I'd be willing to make it more of a hassle to publish them to get that. Packages are consumed more frequently than they are produced.

The main reason for doing this was actually for making consumption easier - one stop shopping for Google APIs. The publishing of a large number of packages can easily be scripted.

The way these APIs are split into packages are controlled using a configuration (https://github.com/dart-lang/googleapis/blob/master/config.yaml) which supports bundling these APIs in a number of packages. The same API can even go into several packages. There is always the option to change or have more than one strategy.

 

Also as APIs gets deprecated (this is especially the case for the googleapis_beta package) we can just remove them, and there are no "stale" API package sitting in pub.dartlang.org.

There won't be a stale package, but there will still be old versions of the monolithic googleapis_beta package that contain those deprecated APIs.

Sure, but if you get the latest version you don't even see an API that is not working any more. 

 

The main reasons for having to bump the version number is when one API changes its interface. In some cases these changes also lead to changes in the wire protocol - in which case switching to the new version might even be required.

I think my main worry here is that you'll be stuck on a very fast-moving version treadmill. Now when any of the APIs makes a change, you have to bump the version and republish all of them. With 65 packages, you may find yourself at major version 4,328 before you know it.

Revving major versions frequently makes your package very hard for users to consume. Shared constraints are common, and a constraint on a package always excludes the next major version that hasn't been released yet (since it may break the package using it). When you rev major versions frequently, it means other packages using you get outdated quickly.

That in itself isn't a problem. Users will just keep using the older version of your package. Where it is a problem is when users have shared dependencies on packages that all depend on googleapis_beta. There's a good chance those two (or more) packages won't depend on the same major version (since the window of time where that was the latest version is small) and you'll end up with a constraint failure.

You can ask the analyzer folks how much pain that caused. :(

Of cause this opens the issue when depending packages are also using one of these packages and you get a violation constraint. However, this can still happen when splitting into several packages if the same API is used.

This is true, but the solver handles a large number of stable packages more easily than a small number of quickly changing ones. It's simpler to pick the latest version of a hundred packages than it is to try to determine which of a small set of packages it should start backtracking on.

Cheers!

- bob

--

For other discussions, see https://groups.google.com/a/dartlang.org/
 
For HOWTO questions, visit http://stackoverflow.com/tags/dart
 
To file a bug report or feature request, go to http://www.dartbug.com/new

To unsubscribe from this group and stop receiving emails from it, send an email to misc+uns...@dartlang.org.

[Grant Jason]

Great question there Bob.

I'm surprized there's no response.

[Bob Nystrom]

On Wed, Sep 24, 2014 at 12:22 PM, Grant Jason <grant...@gmail.com> wrote:

I'm surprized there's no response.

There was on the associated misc@ thread, actually, just not on announce@. :)

- bob

[Natalie Weizenbaum]

What do you think about providing a bunch of separate, separately-versioned packages as well as one "one-stop shopping" package that just depends on and re-exports all of the separate packages?

[Justin Fagnani]

On Wed, Sep 24, 2014 at 1:24 PM, 'Natalie Weizenbaum' via Dart Misc <mi...@dartlang.org> wrote:

What do you think about providing a bunch of separate, separately-versioned packages as well as one "one-stop shopping" package that just depends on and re-exports all of the separate packages?

This seems like a very reasonable approach. 

[Paul Brauner]

+1

[Søren Gjesse]

This is an approach that we have also discussed, and it provides a path for us to split out and still keep the bundles making it easy to get started. The feature in pub for having private packages was coming from this, as all these generated packages could share a common package which was not intended for public consumption (otherwise all these packages would contain copies of the same common code). This of cause might lead to the exact same version constraint issue if we break that common package.

[Grant Jason]

So if I understand you correctly Soren, you'll only separate the packages once that pub feature is available?

[Günter Zöchbauer]

I don't see a problem by publishing a package that is not useful on its own. 

This needs one line in the readme and should be done.

If someone wastes time by trying to use a package that says in the readme

    Don't use this package as a direct dependency, it is only to be used by other Google API packages.

he is beyond help.

On Thursday, September 25, 2014 8:29:23 AM UTC+2, Søren wrote:

[Bob Nystrom]

On Thu, Sep 25, 2014 at 3:56 AM, Günter Zöchbauer <gzo...@gmail.com> wrote:

I don't see a problem by publishing a package that is not useful on its own. 

This needs one line in the readme and should be done.

If someone wastes time by trying to use a package that says in the readme

    Don't use this package as a direct dependency, it is only to be used by other Google API packages.

he is beyond help.

I agree. Though, to help make that message clearer, pub now allows packages whose name starts with "_". It's a code smell if you find yourself using one of those packages directly and you don't know precisely what you're doing.

Cheers!

- bob

[Kevin Moore]

Sharing implementations is one reason for this approach.

A second reason: managing dozens of packages is difficult. As Søren said, we always have the option of splitting out packages individually later while exporting them from a centralized googleapis package.

In the mean time we are following Node, Ruby, and a number of other languages and releasing roll-up packages.

It's great to have the feedback that separate packages is desirable.