gargle’s debut on CRAN

  2019/08/20

  r-lib, gargle

  Jenny Bryan

We’re elated to (somewhat belatedly) announce the initial release of gargle on CRAN!

The gargle package (https://gargle.r-lib.org) is meant to take some of the pain out of working with Google APIs. It’s mostly aimed at the maintainers of R packages that call Google APIs. If we’re successful, users won’t really notice gargle, they’ll just feel like these packages got easier to work with and less idiosyncratic.

The timing of this post is motivated by the release of googledrive v1.0.0. As of this version, googledrive gets all of its auth functionality (and more) from gargle. Although we did not blog about it, bigrquery also recently made the switch, with the release of v1.2.0.

If you are interested in the user-facing implications of using gargle, check out the blog post announcing googledrive v1.0.0 and the changelog for bigrquery v1.2.0.

gargle

The gargle package first appeared on CRAN in early June 2019 and has gotten a few small updates as we learn more by wiring it into packages. gargle is already used by:

gargle’s current functionality falls into two domains, which a client package can adopt (or not) separately:

  • Auth: help users authenticate themselves with their Google identity and obtain a token that the wrapper package can use to make authorized requests.
  • Request preparation and response handling: check requests against the machine-readable Discovery Documents that describe Google APIs and process API responses, especially errors.

The long-term stretch goal is to do for R what the official Google API Client Libraries do for other languages, like Python and Java.

Auth via gargle

Under the hood, gargle’s main auth function is token_fetch(), which tries a series of different methods for obtaining a token. The intent is to make auth “just work” in a wide variety of contexts. This makes some flows newly available in the client packages, such as Application Default Credentials ( official Google docs and a more readable 3rd party blog post).

The main change that users will notice is that gargle implements its own way of storing user OAuth tokens between sessions. The httr package, which gargle depends on, has historically used a local .httr-oauth file for this. In contrast, gargle encourages tokens to be stored outside the project, in a hidden directory at the user level, in a key-value store that incorporates the Google user’s email. This makes it harder to accidentally push your tokens to the cloud, easier to use multiple Google identities, and easier to share tokens across projects and packages. Users will notice they need to re-auth and may want to track down and delete vestigial .httr-oauth files.

Articles and docs

The release of gargle has provided an occasion to document several recurring workflows that can be tricky for useRs, which now work the same across multiple packages:

gargle also offers a mechanism for client packages to build the documentation for their auth function from templates stored in gargle. This means that packages using a common design will also use the same words to describe it.

Another set of articles is aimed at package maintainers interested in delegating auth or request & response handling to gargle:

Google is tightening the rules around various aspects of API access (see, e.g., Project Strobe and Elevating user trust in our API ecosystem). I predict the main thing that useRs will notice is that more and more R packages and apps will require the user to get involved in the nitty gritty details of auth. Users will need to create their own Google Cloud Platform projects, obtain their own API keys, and their own OAuth client IDs and secrets. The overall rationale for Google’s changes makes sense, but the way people use open source R packages is an awkward fit with their recommended auth solutions. It’s becoming more difficult for package developers to make auth feel like it “just works”.

The Google-wrapping packages maintained by the tidyverse / r-lib team are now governed by a shared Privacy Policy. This is linked from each package and also from the consent screen whenever auth is facilitated through our OAuth client.

Some gargle history

I find gargle’s origin story find very satisfying. I suspect that Hadley Wickham’s bigrquery (first on CRAN January 2015) has shaped the basic design for how most R packages handle Google auth, directly or indirectly. I can certainly say that Joanna Zhao and I consulted it when developing googlesheets (first on CRAN July 2015). I know that Mark Edmondson was influenced, in turn, by googlesheets, when he developed googleAuthR (first on CRAN August 2015), used in his suite of packages. By the time Lucy D’Agostino McGowan and I created googledrive (first on CRAN August 2017), I’d developed some strong opinions about how to modify httr’s default behaviour for work with Google APIs. I was also working with Hadley Wickham at RStudio by that point and Lucy and I benefited from his design advice. In May-ish 2017, leading up to rOpenSci’s 2017 Unconf, Craig Citro opened an issue to generate discussion about how to de-duplicate even more API pain, especially for Google APIs. He has a wealth of experience from his role in shaping the official Python client and he made the initial commits that laid the foundation for gargle::token_fetch().

Starting from a common origin (bigrquery), all these people and packages have explored different aspects of this problem space and have developed various solutions. gargle represents the distillation of a lot of hard-won experience and a promising space for future consolidation.

Thanks!

Thanks to all those who have helped get gargle to its first release:

@andrie, @batpigandme, @byapparov, @craigcitro, @dlebech, @hadley, @jennybc, @jonthegeek, @MarkEdmondson1234, @wlongabaugh, and @ZainRizvi

Contents