GraphQLClient.jl

A Julia GraphQL client for seamless integration with a server

This package is intended to make connecting to and communicating with GraphQL servers easy whilst integrating easily with the wider Julia ecosystem.

Key Features

• Querying, mutating and subscribing without manual writing of query strings
• @gql_str non-standard string literal which which validates a query string at compile time
• Deserializing responses directly using StructTypes
• Type stable querying
• Construction of Julia types from GraphQL objects
• Using introspection to help with querying

Installation

The package can be installed with Julia's package manager, either by using the Pkg REPL mode (press ] to enter):

pkg> add GraphQLClient

or by using Pkg functions

julia>using Pkg; Pkg.add("GraphQLClient")

Basic Usage

Connecting to a server

A client can be instantiated by using the Client type

using GraphQLClient
client =Client("https://countries.trevorblades.com")

This will, by default, use a query to introspect the server schema.

We can also set a global client to be used by queries, mutations, subscriptions and introspection functions.

global_graphql_client(Client("https://countries.trevorblades.com"))

Querying

We can query a client without having to type a full GraphQL query by hand, with the response containing fields obtained by introspection

response =query(client, "countries")

Or we can query the global client

response =query("countries")

We can add arguments and specify fields in the response

query_args =Dict("filter"=>Dict("code"=>Dict("eq"=>"AU")))
response =query("countries"; query_args=query_args, output_fields="name");
response.data["countries"]
# 1-element Vector{Any}:# Dict{String, Any}("name" => "Australia")

Or we can query with the query string directly using either a normal String or the gqlnon-standard string literal which also performs some validation of the string:

query_string =gql""" query( $eq: String ){ countries( filter:{ code:{ eq:$eq } } ){ name }}"""
variables =Dict("eq"=>"AU")
response = GraphQLClient.execute(query_string, variables=variables)

We can define a StructType to deserialise the result into

using StructTypes
struct CountryName
name::Stringend
StructTypes.StructType(::Type{CountryName}) = StructTypes.OrderedStruct()
response =query("countries", Vector{CountryName}, query_args=query_args, output_fields="name")
response.data["countries"][1]
# CountryName("Australia")

Or we can use introspection to build the type automatically

Country = GraphQLClient.introspect_object("Country")
response =query("countries", Vector{Country}, query_args=query_args, output_fields="name")
response.data["countries"][1]
# Country# name : Australia

Mutations

Mutations can be constructed in a similar way, except the arguments are not a keyword argument as typically a mutation is doing something with an input. For example

response =mutate(client, "mutation_name", Dict("new_id"=>1))
response =mutate("mutation_name", Dict("new_id"=>1)) # Use global client

Subscriptions

The subscriptions syntax is similar, except that we use Julia's do notation

open_subscription(
client,
"subscription_name",
sub_args=("id"=>1),
output_fields="val"
) do response
val = response.data["subscription_name"]["val"]
stop_sub = val ==2return stop_sub # If this is true, the subscription endsend