Dennis Irorere

Scott Chamberlain

### Introduction

Few months ago, I embarked on a full stack spatial data project at work.
The project kicked off amazingly, until I was almost backed to the wall
when I discovered that some of the data sources were served via a
GraphQL API. Before now, I haven't worked with GraphQL. But, I have
heard a lot about it and how amazing it is for querying data.

GraphQL is a query language for application programming interfaces
(APIs) that prioritizes giving clients exactly the data they request.
It's designed to make APIs flexible, fast and friendly. Basically, it is
used to load data from a server to a client and it does this in a much
more efficient manner than traditional methods and services.

I started off installing the [GraphQL
playground](https://www.graphqlbin.com/v2/new), which is now my go to
tool to interact with GraphQL API and it offers a great workflow to
understand the schema and structure of any GraphQL API. I recommend you
try it out.

After hours of trying out the GraphQL playground, I finally understood
the schema of the GraphQL API endpoint for the project I'm working on.
Well, that was the easy part I must say.

Now that I can query the API, everything should seem great. Right? Well,
it's not. Why? Well, the GraphQL API I was working with fetches the
geospatial data as json file instead of geojson. Probably, because of my
lack of understanding of how GraphQL truly worked with spatial data. The
issue now is, I can see my data. But, just not in the format that I can
work with. I am tempted to talk about the technicality behind it, but I
won't... maybe another time.

### How did I find out about ghql?

At work, our scripting language of choice is R. R is a free software
environment for statistical computing and graphics. Well, that's how
it's officially defined. But, trust me its gradually evolving to do more
than statistical computing and making of beautiful graphics. It was time
for me to programmatically access data with GraphQL API from R. I felt
excited because, I'm an R lover. But, I knew it was a going to be a huge
work, I guess I was ready for the huge work.

After spending days researching about the R packages that can interact
with a GraphQL API, I found three packages. I picked `ghql` over the
others because, it was an rOpenSci package.

### Moving on

In order for R to interact with any GraphQL API, it requires a GraphQL
client. That's where `ghql`, a GraphQL client for R, developed by Scott
Chamberlain comes into play. Still confused? Well, so was I at first. I
tried interacting with a GraphQL server in R and felt like giving up
even before getting anywhere. Hopefully this blog post will assist
others.

<figure class="center">
<img src="GHQL.png" width="350"
alt="GraphQL client and R connection flow" />
<figcaption aria-hidden="true"><p>GraphQL client and R connection
flow</p></figcaption>
</figure>

### Working with `Countries List`, a GraphQL public API

Let's say you were working on a project that required country-specific
data, such as currency, or language. You could get such data from the
[Countries GraphQL API](https://github.com/trevorblades/countries) which
is a public GraphQL API for information about countries, continents, and
languages. This public API uses [Countries
List](https://annexare.github.io/Countries/) and
[provinces](https://github.com/substack/provinces) as data sources, so
the schema follows the shape of those data, with a few exceptions:

- The codes used to key the objects in the original data are available
  as a code property on each item returned from the API.
- The country.continent and country.languages are objects and arrays of
  objects, respectively.
- Each Country has an array of states populated by their
  states/provinces, if any.

Loading the libraries

::: {.highlight}
``` {.chroma tabindex="0"}
library(ghql)library(jsonlite)library(dplyr)
```
:::

Link to the GraphQL schema api

::: {.highlight}
``` {.chroma tabindex="0"}
link <- 'https://countries.trevorblades.com/'
```
:::

Create a new graphqlClient object

::: {.highlight}
``` {.chroma tabindex="0"}
conn <- GraphqlClient$new(url = link)
```
:::

Define a Graphql Query

::: {.highlight}
``` {.chroma tabindex="0"}
query <- 'query($code: ID!){  country(code: $code){    name    native    capital    currency    phone    languages{      code      name    }  }}'
```
:::

The `ghql` query class and define query in a character string

::: {.highlight}
``` {.chroma tabindex="0"}
new <- Query$new()$query('link', query)
```
:::

Inspecting the schema

::: {.highlight}
``` {.chroma tabindex="0"}
new$link
```
:::

``` {tabindex="0"}
##  ##  ## query($code: ID!){##   country(code: $code){##     name##     native##     capital##     currency##     phone##     languages{##       code##       name##     }##   }## }
```

Define a variable as a named list

::: {.highlight}
``` {.chroma tabindex="0"}
variable <- list(  code = "DE")
```
:::

Making a request, passing in the query and then the variables. Then you
convert the raw object to a structured json object

::: {.highlight}
``` {.chroma tabindex="0"}
result <- conn$exec(new$link, variables = variable) %>%  fromJSON(flatten = F)result
```
:::

``` {tabindex="0"}
## $data## $data$country## $data$country$name## [1] "Germany"#### $data$country$native## [1] "Deutschland"#### $data$country$capital## [1] "Berlin"#### $data$country$currency## [1] "EUR"#### $data$country$phone## [1] "49"#### $data$country$languages##   code   name## 1   de German
```

Convert the json data into a tibble object

::: {.highlight}
``` {.chroma tabindex="0"}
country_data <- result$data$country %>%  as_tibble()country_data
```
:::

``` {tabindex="0"}
## # A tibble: 1 x 6##   name    native      capital currency phone languages$code $name##   <chr>   <chr>       <chr>   <chr>    <chr> <chr>          <chr>## 1 Germany Deutschland Berlin  EUR      49    de             German
```

## More examples

Working with a GraphQL API without a defined variable named list

::: {.highlight}
``` {.chroma tabindex="0"}
link <- 'https://countries.trevorblades.com/'# R6 class for constructing graphql queriesconn <- GraphqlClient$new(url = link)## Define query## Create a query class firstqry <- Query$new()## The graphQL server schemaqry$query('x', '{continent(code: "AF") {    countries{    code    name    native    capital    currency    phone    languages {      name    }    }}  }          ')## Execute the queryres <- conn$exec(qry$queries$x)# Convert the the output from raw to json formatres <- jsonlite::fromJSON(res,                          flatten = TRUE)## convert the from json to dataframe objectres_data <- res$data$continent$countries %>%  as_tibble()## Inspect the first 6 rows of the datares_data
```
:::

``` {tabindex="0"}
## # A tibble: 58 x 7##    code  name             native            capital   currency phone languages  ##    <chr> <chr>            <chr>             <chr>     <chr>    <chr> <list>     ##  1 AO    Angola           Angola            Luanda    AOA      244   <df[,1] [1~##  2 BF    Burkina Faso     Burkina Faso      Ouagadou~ XOF      226   <df[,1] [2~##  3 BI    Burundi          Burundi           Bujumbura BIF      257   <df[,1] [2~##  4 BJ    Benin            Bénin             Porto-No~ XOF      229   <df[,1] [1~##  5 BW    Botswana         Botswana          Gaborone  BWP      267   <df[,1] [2~##  6 CD    Democratic Repu~ République démoc~ Kinshasa  CDF      243   <df[,1] [5~##  7 CF    Central African~ Ködörösêse tî Bê~ Bangui    XAF      236   <df[,1] [2~##  8 CG    Republic of the~ République du Co~ Brazzavi~ XAF      242   <df[,1] [2~##  9 CI    Ivory Coast      Côte d'Ivoire     Yamousso~ XOF      225   <df[,1] [1~## 10 CM    Cameroon         Cameroon          Yaoundé   XAF      237   <df[,1] [2~## # ... with 48 more rows
```

### The last dance (conclusion)

So, you have stuck with me this far? Thanks!

My final thought. I think GraphQL can greatly simplify data needs for
both client product developers, server-side engineers and data
scientist. It's still early to assertain the extent of it's impact in
the technological world. But, it seems very promising since the Team
behind GraphQL are continously improving the technology, and there is a
growing community.


Introduction   Few months ago, I embarked on a full stack spatial data project at work. The project kicked off amazingly, until I was almost backed to the wall when I discovered that some of the data sources were served via a GraphQL API. Before now, I haven’t worked with GraphQL. But, I have heard a lot about it and how amazing it is for querying data.

Accessing GraphQL from R

rOpenSci

Stefanie Butland

### rOpenSci HQ

- The recording, collaborative notes and links to community discussion
  and resources are up for our latest [Community Call on Maintaining an
  R package](/commcalls/2020-03-18/). Panel moderated by Julia Silge
  included Elin Waring, Erin Grand, Leonardo Collado-Torres, and Scott
  Chamberlain.

 

### Software Peer Review

1 staff-contributed package passed [software peer
review](/software-review/).

- **[parzer](https://docs.ropensci.org/parzer/)** - Parse messy
  geographic coordinates. Author: [Scott
  Chamberlain](/author/scott-chamberlain/); Reviewers: [Julien
  Brun](https://github.com/brunj7), [María Victoria
  Munafó](https://github.com/mvickm); Read the
  [Review](https://github.com/ropensci/onboarding/issues/341)

*On March 16, we paused new submissions for software peer review for 30
days (possibly longer) in the interest of reducing load on reviewers and
editors in light of the COVID-19 crisis.*

 

### Software

5 new packages from the community and our staff are on CRAN.

- **[ghql](https://docs.ropensci.org/ghql/)** - General purpose GraphQL
  client for R. Author: [Scott Chamberlain](/author/scott-chamberlain/)

- **[osfr](https://docs.ropensci.org/osfr/)** - Interface to the Open
  Science Framework (OSF). Author: [Aaron
  Wolen](https://github.com/aaronwolen)

- **[outsider.base](https://docs.ropensci.org/outsider.base/)** - Base
  package for [outsider](https://docs.ropensci.org/outsider/). Author:
  [Dom Bennett](/author/dom-bennett/)

- **[parzer](https://docs.ropensci.org/parzer/)** - Parse messy
  geographic coordinates. Author: [Scott
  Chamberlain](/author/scott-chamberlain/)

- **[taxadb](https://docs.ropensci.org/taxadb/)** - A High-Performance
  Local Taxonomic Database Interface. Author: [Kari
  Norman](/author/kari-norman/)

<figure class="center">
<img src="2months2mins_hex_apr2020_wh.png" width="500"
alt="hex logos of R packages osfr outsider opentripplanner taxadb" />
</figure>

 

### On the Blog

#### From the rOpenSci team

- [**parzer**: Parse Messy Geographic
  Coordinates](/technotes/2020/03/19/parzer/) Tech Note - [Scott
  Chamberlain](/author/scott-chamberlain/)

- [10 Things We Learned in Creating the Blog Guide with
  bookdown](/blog/2020/04/07/bookdown-learnings/) - [Stefanie
  Butland](/author/stefanie-butland/), [Maëlle
  Salmon](/author/ma%C3%ABlle-salmon/)

- [2 Months in 2 Minutes - rOpenSci News, February
  2020](/blog/2020/02/20/news-feb2020/) - [Stefanie
  Butland](/author/stefanie-butland/)

#### From the community

- [rOpenSci's Leadership in \#rstats
  Culture](/blog/2020/02/21/ropensci-leadership/) - [Julia Stewart
  Lowndes](/author/julia-stewart-lowndes/)

- [**opentripplanner**: Fast and Easy Multimodal Trip Planning in R with
  OpenTripPlanner](/technotes/2020/02/25/opentripplanner/) Tech Note -
  [Malcolm Morgan](/author/malcolm-morgan/)

- [Supercharge your GitHub Actions Experience with
  **tic**](/technotes/2020/03/13/tic-ghactions/) Tech Note - [Patrick
  Schratz](/author/patrick-schratz/)

 

### Use Cases

- 76 published works cited or used rOpenSci software (listed in
  individual newsletters)

- 2 use cases for our packages or resources were posted in our
  [discussion forum](https://discuss.ropensci.org/c/usecases) Look for
  **microdemic**, **magick**

*Have you used an rOpenSci package? [Share your use
case](https://discuss.ropensci.org/c/usecases) and we'll tweet about
it.*

 

### From the Forum

*We have a discussion forum (using Discourse) for the rOpenSci
community. It's a really nice way to have conversations on the internet.
From time to time we'll highlight recent discussions of interest.*

- Peter Desmet asked a question that many R package maintainers run in
  to: [What if raw data in package is too
  large?](https://discuss.ropensci.org/t/what-if-raw-data-in-package-is-too-large/1955)

- Emilio Bruna asked: [What is best practice when a dependency is
  removed from
  CRAN?](https://discuss.ropensci.org/t/what-is-best-practice-when-a-dependency-is-removed-from-cran/1971)

 

### In the News

- [Python 101: Learning About
  Lists](https://www.blog.pythonlibrary.org/2020/03/10/python-101-learning-about-lists/) -
  A good introduction to lists in Python; they're kind of like R lists.
  It's an important data structure to know if you're going to be
  learning Python

- [Necessary &
  Sufficient](https://blog.testdouble.com/posts/2020-02-25-necessary-and-sufficient/) -
  A good read on how to think about testing in general

 

### Keep up with rOpenSci

We create a newsletter every two weeks. You can subscribe via rss feed
in [XML](https://news.ropensci.org/feed.xml) or
[JSON](https://news.ropensci.org/feed.json) or via our one-way [mailing
list](/#subscribe).

Follow [@rOpenSci](https://twitter.com/ropensci) on Twitter.

 

Find out how you can
[contribute](https://devguide.ropensci.org/contributingguide.html) to
rOpenSci as a user or developer.


rOpenSci HQ  The recording, collaborative notes and links to community discussion and resources are up for our latest Community Call on Maintaining an R package. Panel moderated by Julia Silge included Elin Waring, Erin Grand, Leonardo Collado-Torres, and Scott Chamberlain.   Software Peer Review   1 staff-contributed package passed software peer review.
<strong>
 parzer
</strong>
- Parse messy geographic coordinates.

2 Months in 2 Minutes - rOpenSci News, April 2020

Maëlle Salmon

Our onboardingreviews,that ensure that packages contributed by the community undergo atransparent, constructive, non adversarial and open review process, takeplace in the issue tracker of a GitHub repository. Development of thepackages we onboard also takes place in the open, most often in GitHubrepositories.

Messaggi di Rogue Scholar

Accessing GraphQL from R

2 Months in 2 Minutes - rOpenSci News, April 2020

Rectangling onboarding