GraphQL logo — http://graphql.org/

Get the client library from https://github.com/machinebox/graphql

We might see a surge of GraphQL APIs next year, and there are already a few popping up. Most provide an HTTP API, but there are some strange specifics that make consuming them tricky if you never have before.

Thanks to Chris Broadfoot from Google for his input on client design, the footprint of this package is relatively small and pretty obvious:

Godoc index for machinebox/graphql — https://godoc.org/github.com/machinebox/graphql

It’s very easy to use — we just create a Client using NewClient , specifying the endpoint of the GraphQL API we want to make requests to:

Next, we need to make a graphql.Request , which takes a GraphQL query string.

Read more about queries in the GraphQL documentation.

// make a request

req := graphql.NewRequest(`

query ($key: String!) {

items (id:$key) {

field1

field2

field3

}

}

`)

Using backticks for the string is nice because we can span multiple lines (making the query easier to read) and even use single or double quotes in the query.

The $key token is a variable, and it is recommended that you use them to pass data into queries for two main reasons:

You can write queries once, and don’t have to build strings every time More importantly, nobody can inject harmful or stupid things into your query string

Now we have specified that there will be a $key variable, we need to provide a value for it which is easy using the Var method:

req.Var("key", "value")

If we want to upload a file as part of the request, we can use the req.File method.

Assuming we expect to get some data back from the GraphQL API, we can build a normal Go struct to receive it in the same way we might if we were consuming a JSON API:

type response struct {

Name string

Items struct {

Records []struct{

Title string

}

}

}

Once our Request is ready and our response object is defined, we can use the client that we created earlier to run it:

ctx := context.Background() var res response

if err := client.Run(ctx, req, &res); err != nil {

log.Fatal(err)

}

Alternatively, if we only care that the request was successful but not what the response contains, we can just pass nil instead of a response object.

The Run method will make the request and unmarshal the response into the res object ready to use. Or it might return an error, which may be an HTTP transport issue, a JSON encoding/decoding issue, or an error returned from the remote GraphQL service.

The Run method takes a context.Context too, which allows you to cancel the request, or specify a sensible timeout etc.

Try it, and get involved

Please use the package and get involved if you can improve it. This project aims to provide the bare bones of what a Go programmer would need in order to start consuming GraphQL services, without bloating into a big complicated package.