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.

Import package. Line 7–10: Define a GraphQL object type named Query , with a latestPost field.

Define a GraphQL object type named , with a field. Line 11: Define latestPost as a built-in GraphQL String scalar type.

Define 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.

Return a string of value “ ” 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,

Create a HTTP.Handler that handles GraphQL requests, Line 22: … with our previously defined schema,

… 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.

…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

Add our handler to an endpoint, 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: