Learn Golang + GraphQL + Relay #1

Hafiz Ismail

Published in

wehavefaces

4 min readOct 7, 2015

Part 1: Your first Golang GraphQL server

(Update Nov 4 2015: Huge breaking changes in the API to improve readability and usability of the package )

This will be the first in a multi-part series tutorial introducing Golang to Facebook’s GraphQL and Relay.

This week, we will start off with a simple but very achievable goal:
to build a GraphQL server in Golang.

We’ll introduce a couple of useful Golang packages along the way that will help us achieve just that.

Before we begin

This part of the series, we will assume that you have at least heard of GraphQL (http://graphql.org), and was curious enough to have already read some literature on it, or watched a couple of introductory videos about it, allowing you to have some basic concept of what’s going on here.

If you just want to quickly get started on using GraphQL with Golang,
this article is just for you.

Getting started

Let’s get down right to it. We’ll start real simple.

Our server will have only one latestPost field in its top-level Query, which returns a value (“Hello World”, of course) which is of the built-in GraphQL type, String.

Using GraphQL’s type system shorthand notation:

Simple as that. No fuss.

Next, we will use that as our blueprint and define our GraphQL schema in Golang.

Introducing graphql-go

The NodeJS/Javascript community has graphql-js which was released by Facebook as a technical preview; soon after, the Ruby community has graphql-ruby. Now Golang has its own graphql-go.

(Note: At the time of writing, Oct 7 2015, graphql-go is still in early infant stages — barely alpha, and needs much more attention and TLC from the community for it to mature.)

The benefit of using graphql-go is that it has near-identical API to graphql-js; so it’ll be easy to read another GraphQL schema written for NodeJS/Javascript and and you’ll still be able to re-write it for Golang.

GraphQL schema definition in Golang

Let’s write our previously established schema in Golang using graphql-go (followed by its equivalent in JavaScript using graphql-js).

Create a main.go file and add the following code:

Well, both of them seem similar enough to each other. But we’ll only need the one in Golang in this tutorial.

What we have done above is simply:

Line 4: Import graphql-go package.
Line 7–10: Define a GraphQL object type named Query, with a latestPost field.
Line 11: Define latestPost as a built-in GraphQL String scalar type.
Line 12: Return a string of value “Hello World” for latestPost field. This means that whenever the field is queried, our server will return that string. Easy peezy.
Line 19: Define our GraphQL schema with our Query object (queryType) as its top-level root query.

Now that we have a schema, let’s get cooking!

A Golang GraphQL server in 10 lines or less

With our schema definition, we can now create a GraphQL server with the built-in net/http package and a nifty little package to serve GraphQL query requests: graphql-go-handler.

graphql-go-handler is simply a package that creates a HTTP.Handler that we can plug into the net/http HTTP server.

2. To use it with our schema, add the following code to previous main.go file.

Apart from the schema, the code to get a server running is barely a handful.

Line 21: Create a HTTP.Handler that handles GraphQL requests,
Line 22: … with our previously defined schema,
Line 23: …and for an added bonus, we set it to format the JSON response nicely, with indentation and all.
Line 27: Add our handler to an endpoint, /graphql
Line 30: And serve it at port 8080

Other than that, there isn’t much to it.

Get ready to start those engines and hear it roar!

3. Run the main.go file we just written.

$ go run main.go

The GraphQL server will now be running at http://localhost:8080/graphql

To test it, run the following curl command on your terminal:

If nothing goes wrong, you should see the following response from the server:

And there you go; writing a GraphQL server in Golang can’t get any easier than that. Huzzah!

Mission accomplished!

What’s next?

Now that you have a GraphQL server running, you can play around with the code that you’ve just written, and get comfortable. Here are some suggestions to get you started:

Modify the server to return a string other than “Hello World” when latestPost field is queried. Easy.
Update the schema and define another field that returns a random integer (hint: GraphQLInt). Peezy.
Update the server to serve graphiql (an amazing in-browser IDE for building GraphQL queries) at http://localhost:8080
(Basically, build your own version of golang-graphql-playground). Lemon.
Or simply download the standalone version graphiql-app and get comfortable sending GraphQL requests to your server. (Or you can choose to stick with curl if thats your thing, it’s all cool). Squeezy.

Next week, tune in to the next part of our series, where we will look into creating your first React/Relay application, driven by the Golang GraphQL server that you just build.

The source for this tutorial is available on Github. Follow me @sogko on Twitter and Github, because that’s a thing now.