A GraphQL client library for Go

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:

client := graphql.NewClient("https://machinebox.io/graphql")

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:

1. You can write queries once, and don’t have to build strings every time
2. 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.

What is Machine Box?

Machine Box puts state of the art machine learning capabilities into Docker containers so developers like you can easily incorporate natural language processing, facial detection, object recognition, etc. into your own apps very quickly.

The boxes are built for scale, so when your app really takes off just add more boxes horizontally, to infinity and beyond. Oh, and it’s way cheaper than any of the cloud services (and they might be better)… and your data doesn’t leave your infrastructure.

Have a play and let us know what you think. :)

Build real tools, apps and services while exploring good practices in Go.

Go Programming Blueprints: Second Edition

Buy now