Title: | General Purpose 'GraphQL' Client |
---|---|
Description: | A 'GraphQL' client, with an R6 interface for initializing a connection to a 'GraphQL' instance, and methods for constructing queries, including fragments and parameterized queries. Queries are checked with the 'libgraphqlparser' C++ parser via the 'graphql' package. |
Authors: | Scott Chamberlain [aut] |
Maintainer: | Mark Padgham <[email protected]> |
License: | MIT + file LICENSE |
Version: | 0.1.1.099 |
Built: | 2024-08-29 23:14:32 UTC |
Source: | https://github.com/ropensci/ghql |
General purpose GraphQL client
The main interface in this package is [GraphqlClient], which produces a client (R6 class) with various methods for interacting with a GraphQL server. [GraphqlClient] also accepts various input parameters to set a base URL, and any headers required, which is usually the required set of things needed to connect to a GraphQL service.
[Query] is an interface to creating GraphQL queries, which works together with [GraphqlClient]
[Fragment] is an interface to creating GraphQL fragments, which works together with [GraphqlClient]
Scott Chamberlain [email protected]
ghql fragment class
a 'Fragment' class (R6 class)
fragments
(list) list of fragments
print()
print method for the 'Fragment' class
Fragment$print(x, ...)
x
self
...
ignored
fragment()
create a fragment by name
Fragment$fragment(name, x)
name
(character) fragment name
x
(character) the fragment
nothing returned; sets fragments internally
# make a fragment class frag <- Fragment$new() # define a fragment frag$fragment('Watchers', ' fragment on Repository { watchers(first: 3) { edges { node { name } } } }') # define another fragment frag$fragment('Stargazers', ' fragment on Repository { stargazers(first: 3) { edges { node { name } } } }') frag frag$fragments frag$fragments$Watchers frag$fragments$Stargazers
# make a fragment class frag <- Fragment$new() # define a fragment frag$fragment('Watchers', ' fragment on Repository { watchers(first: 3) { edges { node { name } } } }') # define another fragment frag$fragment('Stargazers', ' fragment on Repository { stargazers(first: 3) { edges { node { name } } } }') frag frag$fragments frag$fragments$Watchers frag$fragments$Stargazers
R6 class for constructing GraphQL queries
a 'GraphqlClient' class (R6 class)
url
(character) list of fragments
headers
list of named headers
schema
holds schema
result
holds result from http request
fragments
(list) list of fragments
new()
Create a new 'GraphqlClient' object
GraphqlClient$new(url, headers)
url
(character) URL for the GraphQL schema
headers
Any acceptable headers, a named list. See examples
A new 'GraphqlClient' object
print()
print method for the 'GraphqlClient' class
GraphqlClient$print(x, ...)
x
self
...
ignored
ping()
ping the GraphQL server
GraphqlClient$ping(...)
...
curl options passed on to [crul::verb-HEAD]
'TRUE' if successful response, 'FALSE' otherwise
load_schema()
load schema, from URL or local file
GraphqlClient$load_schema(schema_url = NULL, schema_file = NULL, ...)
schema_url
(character) url for a schema file
schema_file
(character) path to a schema file
...
curl options passed on to [crul::verb-GET]
nothing, loads schema into '$schema' slot
dump_schema()
dump schema to a local file
GraphqlClient$dump_schema(file)
file
(character) path to a file
nothing, writes schema to 'file'
schema2json()
convert schema to JSON
GraphqlClient$schema2json(...)
...
options passed on to [jsonlite::toJSON()]
json
fragment()
load schema, from URL or local file
GraphqlClient$fragment(name, x)
name
(character) fragment name
x
(character) the fragment
nothing returned; sets fragments internally
exec()
execute the query
GraphqlClient$exec( query, variables, encoding = "UTF-8", response_headers = FALSE, ... )
query
(character) a query, of class 'query' or 'fragment'
variables
(list) named list with query variables values
encoding
(character) encoding to use to parse the response. passed on to [crul::HttpResponse] '$parse()' method. default: "UTF-8"
response_headers
If 'TRUE', include the response headers as an attribute of the return object.
...
curl options passed on to [crul::verb-POST]
character string of response, if successful
prep_query()
not used right now
GraphqlClient$prep_query(query)
query
(character) a query, of class 'query' or 'fragment'
x <- GraphqlClient$new() x ## Not run: # make a client token <- Sys.getenv("GITHUB_TOKEN") cli <- GraphqlClient$new( url = "https://api.github.com/graphql", headers = list(Authorization = paste0("Bearer ", token)) ) # if the GraphQL server has a schema, you can load it cli$load_schema() # dump schema to local file f <- tempfile(fileext = ".json") cli$dump_schema(file = f) readLines(f) jsonlite::fromJSON(readLines(f)) # after dumping to file, you can later read schema from file for faster loading rm(cli) cli <- GraphqlClient$new( url = "https://api.github.com/graphql", headers = list(Authorization = paste0("Bearer ", token)) ) cli$load_schema(schema_file = f) # variables cli$url cli$schema cli$schema$data cli$schema$data$`__schema` cli$schema$data$`__schema`$queryType cli$schema$data$`__schema`$mutationType cli$schema$data$`__schema`$subscriptionType head(cli$schema$data$`__schema`$types) cli$schema$data$`__schema`$directives # methods ## ping - hopefully you get TRUE cli$ping() ## dump schema cli$schema2json() ## define query ### creat a query class first qry <- Query$new() ## another qry$query('repos', '{ viewer { repositories(last: 10, isFork: false, privacy: PUBLIC) { edges { node { isPrivate id name } } } } }') qry qry$queries qry$queries$repos ### execute the query cli$exec(qry$queries$repos) # query with a fragment ### define query without fragment, but referring to it qry <- Query$new() qry$query('queryfrag', '{ ropensci: repositoryOwner(login:"ropensci") { repositories(first: 3) { edges { node { ...Watchers } } } } ropenscilabs: repositoryOwner(login:"ropenscilabs") { repositories(first: 3) { edges { node { ...Watchers } } } } }') ### define a fragment frag <- Fragment$new() frag$fragment('Watchers', ' fragment on Repository { watchers(first: 3) { edges { node { name } } } }') frag$fragments frag$fragments$Watchers ### add the fragment to the query 'queryfrag' qry$add_fragment('queryfrag', frag$fragments$Watchers) qry qry$queries$queryfrag ### execute query: we'll hook together the query and your fragment internally cli$exec(qry$queries$queryfrag) ## End(Not run)
x <- GraphqlClient$new() x ## Not run: # make a client token <- Sys.getenv("GITHUB_TOKEN") cli <- GraphqlClient$new( url = "https://api.github.com/graphql", headers = list(Authorization = paste0("Bearer ", token)) ) # if the GraphQL server has a schema, you can load it cli$load_schema() # dump schema to local file f <- tempfile(fileext = ".json") cli$dump_schema(file = f) readLines(f) jsonlite::fromJSON(readLines(f)) # after dumping to file, you can later read schema from file for faster loading rm(cli) cli <- GraphqlClient$new( url = "https://api.github.com/graphql", headers = list(Authorization = paste0("Bearer ", token)) ) cli$load_schema(schema_file = f) # variables cli$url cli$schema cli$schema$data cli$schema$data$`__schema` cli$schema$data$`__schema`$queryType cli$schema$data$`__schema`$mutationType cli$schema$data$`__schema`$subscriptionType head(cli$schema$data$`__schema`$types) cli$schema$data$`__schema`$directives # methods ## ping - hopefully you get TRUE cli$ping() ## dump schema cli$schema2json() ## define query ### creat a query class first qry <- Query$new() ## another qry$query('repos', '{ viewer { repositories(last: 10, isFork: false, privacy: PUBLIC) { edges { node { isPrivate id name } } } } }') qry qry$queries qry$queries$repos ### execute the query cli$exec(qry$queries$repos) # query with a fragment ### define query without fragment, but referring to it qry <- Query$new() qry$query('queryfrag', '{ ropensci: repositoryOwner(login:"ropensci") { repositories(first: 3) { edges { node { ...Watchers } } } } ropenscilabs: repositoryOwner(login:"ropenscilabs") { repositories(first: 3) { edges { node { ...Watchers } } } } }') ### define a fragment frag <- Fragment$new() frag$fragment('Watchers', ' fragment on Repository { watchers(first: 3) { edges { node { name } } } }') frag$fragments frag$fragments$Watchers ### add the fragment to the query 'queryfrag' qry$add_fragment('queryfrag', frag$fragments$Watchers) qry qry$queries$queryfrag ### execute query: we'll hook together the query and your fragment internally cli$exec(qry$queries$queryfrag) ## End(Not run)
ghql query class
a 'Query' class (R6 class)
queries
(list) list of queries
print()
print method for the 'Query' class
Query$print(x, ...)
x
self
...
ignored
query()
define query in a character string
Query$query(name, x)
name
(character) name of the query
x
(character) the query
nothing returned; sets query with 'name' internally
add_fragment()
add a fragment to a query
Query$add_fragment(query_name, fragment)
query_name
(character) the query name to add the fragment to
fragment
(character) the fragment itself
nothing returned; sets the fragment with the query
parse2json()
parse query string with libgraphqlparser and get back JSON
Query$parse2json(query, parse_schema = FALSE)
query
(character) a query to parse
parse_schema
(logical) enable schema definition parsing? default: 'FAlSE'
adf
we run an internal method 'check_query()' that runs the public method ‘parse2json()' - if the query doesn’t pass the libgraphqlparser parser, we return the error message
# make a client qry <- Query$new() ## define query qry$query('query2', '{ viewer { repositories(last: 10, isFork: false, privacy: PUBLIC) { edges { node { isPrivate id name } } } } }') qry qry$queries qry$queries$query2 # fragments ## by hand qry$query('querywithfrag', '{ ropensci: repositoryOwner(login:"ropensci") { repositories(first: 3) { edges { node { ...Watchers } } } } ropenscilabs: repositoryOwner(login:"ropenscilabs") { repositories(first: 3) { edges { node { ...Watchers } } } } } fragment Watchers on Repository { watchers(first: 3) { edges { node { name } } } }') qry qry$queries qry$queries$querywithfrag ## Not run: token <- Sys.getenv("GITHUB_TOKEN") con <- GraphqlClient$new( url = "https://api.github.com/graphql", headers = list(Authorization = paste0("Bearer ", token)) ) jsonlite::fromJSON(con$exec(qry$queries$querywithfrag)) ## use Fragment class fragments generator ### define query without fragment, but referring to it qry$query('queryfrag', '{ ropensci: repositoryOwner(login:"ropensci") { repositories(first: 3) { edges { node { ...Watchers } } } } ropenscilabs: repositoryOwner(login:"ropenscilabs") { repositories(first: 3) { edges { node { ...Watchers } } } } }') ### define a fragment, and use it later frag <- Fragment$new() frag$fragment('Watchers', ' fragment on Repository { watchers(first: 3) { edges { node { name } } } }') frag$fragments frag$fragments$Watchers ### add the fragment to the query 'queryfrag' qry$add_fragment('queryfrag', frag$fragments$Watchers) qry qry$queries qry$queries$queryfrag ## End(Not run)
# make a client qry <- Query$new() ## define query qry$query('query2', '{ viewer { repositories(last: 10, isFork: false, privacy: PUBLIC) { edges { node { isPrivate id name } } } } }') qry qry$queries qry$queries$query2 # fragments ## by hand qry$query('querywithfrag', '{ ropensci: repositoryOwner(login:"ropensci") { repositories(first: 3) { edges { node { ...Watchers } } } } ropenscilabs: repositoryOwner(login:"ropenscilabs") { repositories(first: 3) { edges { node { ...Watchers } } } } } fragment Watchers on Repository { watchers(first: 3) { edges { node { name } } } }') qry qry$queries qry$queries$querywithfrag ## Not run: token <- Sys.getenv("GITHUB_TOKEN") con <- GraphqlClient$new( url = "https://api.github.com/graphql", headers = list(Authorization = paste0("Bearer ", token)) ) jsonlite::fromJSON(con$exec(qry$queries$querywithfrag)) ## use Fragment class fragments generator ### define query without fragment, but referring to it qry$query('queryfrag', '{ ropensci: repositoryOwner(login:"ropensci") { repositories(first: 3) { edges { node { ...Watchers } } } } ropenscilabs: repositoryOwner(login:"ropenscilabs") { repositories(first: 3) { edges { node { ...Watchers } } } } }') ### define a fragment, and use it later frag <- Fragment$new() frag$fragment('Watchers', ' fragment on Repository { watchers(first: 3) { edges { node { name } } } }') frag$fragments frag$fragments$Watchers ### add the fragment to the query 'queryfrag' qry$add_fragment('queryfrag', frag$fragments$Watchers) qry qry$queries qry$queries$queryfrag ## End(Not run)