Golang and AWS Lambda are two of the primary tools I use everyday for work, so when AWS announced that lambda would natively support Go earlier this year I was ecstatic. In this tutorial, I'll walk through how easy it is to deploy a fully functional API using these technologies and others by way of the serverless framework.

Disclaimer

This tutorial is designed to be deployed to AWS, and while the majority of resources should fall under the free tier, please be aware that this could be costing you actual money.

Some Background

So why is official support for Golang in AWS Lambda so great?

Well, firstly, building a Golang application is dead simple, and this makes deployment dead simple. The output of go build is a statically linked binary, and this is literally the only thing you need to deploy an application to lambda.

Second, Golang enjoys one of the lower cold start times of the currently supported languages, and is likely to improve on that mark in the future.

Also, sometimes you just get tired of javascript.

Setup

Before we get started, we need to prepare our environment. My machine is setup with the following:

• Node.js v8
• Golang 1.10

Once that's squared away, we'll need to install the serverless cli.

npm install -g serverless

You'll also need the aws cli configured with a set of access credentials to an AWS account you control.

Initial Project

Now that we have our tools installed, we can begin setting up a new project. Enter serverless.

$ cd somewhere/in/GOPATH
$ serverless create -t aws-go-dep -p go-lambda-test

Once complete, serverless will scaffold a new project using the aws-go-dep template. This comes with all sorts of goodies:

• dep has been initialized with the aws-lambda-go package.
• Two very simple lambda functions.
• A Makefile for building.
• A serverless.yml configuration file.

In fact, even in this simple form, we are able to deploy the two functions to lambda and test them out. I like to add a new build target to the Makefile to facilitate this. Here's what that looks like:

build:
	dep ensure
	env GOOS=linux go build -ldflags="-s -w" -o bin/hello hello/main.go
	env GOOS=linux go build -ldflags="-s -w" -o bin/world world/main.go

deploy: build
	serverless deploy

From here, we can deploy to AWS and test each function.

$ make deploy
$ serverless invoke -f hello

If everything goes as expected, you should see the following output:

{
    "message": "Go Serverless v1.0! Your function executed successfully!"
}

Taking a look at the provided hello/main.go, it should pretty intuitive to see what's happening here.

package main

import (
	"github.com/aws/aws-lambda-go/lambda"
)

type Response struct {
	Message string `json:"message"`
}

func Handler() (Response, error) {
	return Response{
		Message: "Go Serverless v1.0! Your function executed successfully!",
	}, nil
}

func main() {
	lambda.Start(Handler)
}

Our Handler func is being executed on every lambda function invocation, always returning a static response.

Adding an API

Now that we're starting to get a feel for deploying and executing lambda functions with Golang, let's begin to introduce an API. First, we'll need to install some dependencies and remove the aws-lambda-go dependency.

• gin - http framework
• gateway - lambda wrapper for http.Handler interface

To achieve this, we can run:

$ dep ensure -add github.com/gin-gonic/gin github.com/apex/gateway

You'll likely receive a warning from dep at this point indicating that the installed dependencies are not imported by your project, but we'll address that soon enough. Let's start by creating a new directory for our handler and removing the demo functions.

$ rm -r hello world
$ mkdir cmd
$ touch cmd/handler.go

Once complete, open up cmd/handler.go and enter the following:

package main

import (
	"log"
	"net/http"
	"os"

	"github.com/apex/gateway"
	"github.com/gin-gonic/gin"
)

func foo(c *gin.Context) {
	c.JSON(http.StatusOK, gin.H{"success": true, "message": "hello lambda API!"})
}

func main() {
	addr := ":3000"
	mode := os.Getenv("GIN_MODE")
	g := gin.New()
	g.GET("/foo", foo)

	if mode == "release" {
		log.Fatal(gateway.ListenAndServe(addr, g))
	} else {
		log.Fatal(http.ListenAndServe(addr, g))
	}
}

Basically, what we're doing here boils down to this:

• Instantiating an instance of *gin.Engine.
• Telling that instance to run our foo function when it receives a GET at /foo.
• The most interesting part is how we "start the engine". If the environment variable GIN_MODE is set to "release", we wrap our handler with the gateway package, which basically abstracts the API gateway syntax and allows us to focus on the server itself. Cool, right?
• If GIN_MODE does not equal "release", we start an ordinary http server.

Let's go ahead and start a local server to test with first.

$ go run cmd/handler.go
[GIN-debug] [WARNING] Running in "debug" mode. Switch to "release" mode in production.
 - using env:   export GIN_MODE=release
 - using code:  gin.SetMode(gin.ReleaseMode)

[GIN-debug] GET    /foo                      --> main.foo (1 handlers)

And from a separate terminal window, we can test our simple API using curl.

$ curl localhost:3000/foo
{"message":"hello lambda API!","success":true}

Great! Now that we're confirmed to be working locally, let's update our Makefile and serverless.yml to know about our new function.

First, the Makefile:

build:
	dep ensure
	env GOOS=linux go build -ldflags="-s -w" -o bin/handler cmd/handler.go

deploy: build
	serverless deploy

Then, serverless.yml:

service: blog-test

provider:
  name: aws
  runtime: go1.x

package:
 exclude:
   - ./**
 include:
   - ./bin/**

functions:
  handler:
    handler: bin/handler
    events:
      - http:
          path: /foo
          method: get
    environment:
      GIN_MODE: release

A few things to note on these changes. In the Makefile, we remove the old calls to go build and introduce a new one for our handler. In serverless.yml, we're again removing references to our previous functions and adding our handler.

The more interesting part is the addition of events. This block tells serverless what events need to take place in order to invoke our Lambda function. In this case, we're saying that we want our function to be invoked in response to API gateway receiving a GET request to /foo.

Now, we can deploy.

$ make deploy
dep ensure
env GOOS=linux go build -ldflags="-s -w" -o bin/handler cmd/handler.go
serverless deploy
Serverless: Packaging service...
Serverless: Excluding development dependencies...
Serverless: Uploading CloudFormation file to S3...
Serverless: Uploading artifacts...
Serverless: Uploading service .zip file to S3 (8.07 MB)...
Serverless: Validating template...
Serverless: Updating Stack...
Serverless: Checking Stack update progress...
.......................................
Serverless: Stack update finished...
Service Information
service: blog-test
stage: dev
region: us-east-1
stack: blog-test-dev
api keys:
  None
endpoints:
  GET - https://ko86rwumf6.execute-api.us-east-1.amazonaws.com/dev/foo # here is your endpoint
functions:
  handler: blog-test-dev-handler

Be sure to take special care to note the endpoints section of the output. This is the public URL of your API gateway endpoint and should end in /dev/foo. Let's test that endpoint with curl (yours will be different).

$ curl https://ko86rwumf6.execute-api.us-east-1.amazonaws.com/dev/foo
{"message":"hello lambda API!","success":true}

Awesome! We've just deployed our first API written in Golang to Lambda, fronted by API gateway. From here, the world is your oyster.

Finished

In my next post, we'll look at how to extend our serverless configuration to add a DynamoDB table and integrate that into our API.

Intro

Golang is pretty hot right now. Over the past few weeks, I've been exploring implementing some of the cloud infrastracture I'd previously built with node in go, partly for fun, partly because go is fast. This led me to believe that setting up a basic REST service would make for a great tutorial.

At the end, we will have a fully functioning REST service for serving basic CRUD on a user resource. Code for the final product can be found here.

This is the third and final entry in a series of high level tutorials on setting up a REST service using golang, focused on wiring up our previous webserver to a mongo backend.

Setup mgo

At the end of the last tutorial, we had a functioning, albeit useless, webserver offering some CRUD operations on a user resource. In this entry, we will be tying that to a mongodb backend for persistent data. If you don't have mongo installed on your system, you can find instructions here or install via brew.

The most popular mongo driver for golang is easily mgo. We'll be using two packages provided by mgo, mgo itself and bson. We need to grab each package to get going.

$ go get gopkg.in/mgo.v2
$ go get gopkg.in/mgo.v2/bson

We also need to establish a connection to mongo to provide to our controllers. Add the following function to our server.go.

func getSession() *mgo.Session {
	// Connect to our local mongo
	s, err := mgo.Dial("mongodb://localhost")

	// Check if connection error, is mongo running?
	if err != nil {
		panic(err)
	}
	return s
}

Now, our controller is going to need a mongo session to use in the CRUD methods. Let's change how we get a UserController to the following.

// Get a UserController instance
uc := controllers.NewUserController(getSession())

Update the UserController struct

The first thing we need to do to our UserController is to extend the struct to contain a reference to a *mgo.Session so that our controller methods can access mongo. Update the UserController definition to match the following.

UserController struct {
	session *mgo.Session
}

Next, we need to update our NewUserController function to receive a *mgo.Session and instantiate the controller with it. Update NewUserController to match the following.

func NewUserController(s *mgo.Session) *UserController {
	return &UserController{s}
}

Update the User Model

Before we start updating the controller methods to use mongo, we need to update our model to integrate with mgo. Similar to how we updated the user model to use a json struct tag for outputting JSON data, we need to add a struct tag to tell mgo how to store the user information.

Update user.go in the models directory to contain the following.

package models

import "gopkg.in/mgo.v2/bson"

type (
	// User represents the structure of our resource
	User struct {
		Id     bson.ObjectId `json:"id" bson:"_id"`
		Name   string        `json:"name" bson:"name"`
		Gender string        `json:"gender" bson:"gender"`
		Age    int           `json:"age" bson:"age"`
	}
)

You'll notice that we are importing only the bson package from mgo. The bson package provides an implementation of the bson specification for go. We use this to change the type of our Id field to a bson.ObjectId.

We also extend each field with a bson struct tag to describe the property name of the mongo document containing the user.

Update the POST Controller

Now that our model has been updated and our controller has a reference to an active mongo session, let's start integrating mongo into our service by updating the CreateUser method of our UserController. Update the method to the following.

// CreateUser creates a new user resource
func (uc UserController) CreateUser(w http.ResponseWriter, r *http.Request, p httprouter.Params) {
	// Stub an user to be populated from the body
	u := models.User{}

	// Populate the user data
	json.NewDecoder(r.Body).Decode(&u)

	// Add an Id
	u.Id = bson.NewObjectId()

	// Write the user to mongo
	uc.session.DB("go_rest_tutorial").C("users").Insert(u)

	// Marshal provided interface into JSON structure
	uj, _ := json.Marshal(u)

	// Write content-type, statuscode, payload
	w.Header().Set("Content-Type", "application/json")
	w.WriteHeader(201)
	fmt.Fprintf(w, "%s", uj)
}

There are two significant changes here. First, we ask the bson package for a new ObjectId to store on our user. Second, we write the user to the users collection in the go_rest_tutorial database.

Let's test adding a user.

$ curl -XPOST -H 'Content-Type: application/json' -d '{"name": "Bob Smith", "gender": "male", "age": 50}' http://localhost:3000/user
{"id":"5497246c380a967ff1000003","name":"Bob Smith","gender":"male","age":50}

Awesome! Our user was stored in mongo and we have successfully generated an ObjectId.

Update the GET Controller

Now that we are able to create new users, it would be nice to be able to fetch them as well. To do this, let's update the GetUser method of our UserController to the following.

// GetUser retrieves an individual user resource
func (uc UserController) GetUser(w http.ResponseWriter, r *http.Request, p httprouter.Params) {
	// Grab id
	id := p.ByName("id")

	// Verify id is ObjectId, otherwise bail
	if !bson.IsObjectIdHex(id) {
		w.WriteHeader(404)
		return
	}

	// Grab id
	oid := bson.ObjectIdHex(id)

	// Stub user
	u := models.User{}

	// Fetch user
	if err := uc.session.DB("go_rest_tutorial").C("users").FindId(oid).One(&u); err != nil {
		w.WriteHeader(404)
		return
	}

	// Marshal provided interface into JSON structure
	uj, _ := json.Marshal(u)

	// Write content-type, statuscode, payload
	w.Header().Set("Content-Type", "application/json")
	w.WriteHeader(200)
	fmt.Fprintf(w, "%s", uj)
}

Again, there a couple of significant changes. First, we are converting our id path parameter to a bson.ObjectId to be used to find the user. In the event that the id cannot be converted, we bail with a 404 Not Found. Second, we use our mongo session to find a user matching the provided id from the users collection. We also added an error check when we find the user to deliver a 404 Not Found.

Let's test it out by grabbing the user we created previously.

$ curl http://localhost:3000/user/5497246c380a967ff1000003
{"id":"5497246c380a967ff1000003","name":"Bob Smith","gender":"male","age":50}

Sweet! We got the same user that we had posted above. Now if we change the id we should get a 404.

$ curl -i http://localhost:3000/user/5497246c380a967ff1000004
HTTP/1.1 404 Not Found
Date: Sun, 21 Dec 2014 19:58:34 GMT
Content-Length: 0
Content-Type: text/plain; charset=utf-8

Update the DELETE Controller

So we are able to create new users and retrieve them, now let's add the ability to remove them. To accomplish this, let's update the RemoveUser method of our controller to the following.

// RemoveUser removes an existing user resource
func (uc UserController) RemoveUser(w http.ResponseWriter, r *http.Request, p httprouter.Params) {
	// Grab id
	id := p.ByName("id")

	// Verify id is ObjectId, otherwise bail
	if !bson.IsObjectIdHex(id) {
		w.WriteHeader(404)
		return
	}

	// Grab id
	oid := bson.ObjectIdHex(id)

	// Remove user
	if err := uc.session.DB("go_rest_tutorial").C("users").RemoveId(oid); err != nil {
		w.WriteHeader(404)
		return
	}

	// Write status
	w.WriteHeader(200)
}

As you can see, we are again getting an ObjectId out of the id path parameter, and bailing with a 404 if the id cannot by converted to an ObjectId. We then remove the document matching this id and deliver a 200.

We can test this by first deleting the user we created, then trying to fetch the user.

$ curl -XDELETE http://localhost:3000/user/5497246c380a967ff1000003
$ curl -i http://localhost:3000/user/5497246c380a967ff1000003
HTTP/1.1 404 Not Found
Date: Sun, 21 Dec 2014 20:04:28 GMT
Content-Length: 0
Content-Type: text/plain; charset=utf-8

Great! We removed the user and confirmed that the user no longer exists.

Fin

This is end of the tutorial on adding a backend to our REST service, and also the end of the tutorial series in general. While there most certainly are many improvements to be made, such as adding some security and much better error handling, hopefully this high-level overview has been beneficial.

Resources

• mongodb
• mgo

Intro

Golang is pretty hot right now. Over the past few weeks, I've been exploring implementing some of the cloud infrastracture I'd previously built with node in go, partly for fun, partly because go is fast. This led me to believe that setting up a basic REST service would make for a great tutorial.

At the end, we will have a fully functioning REST service for serving basic CRUD on a user resource. Code for the final product can be found here.

This is the second in a series of high level tutorials on setting up a REST service using golang, focused on using public packages and defining a basic webserver.

Packages

Go allows for external packages to be accessed in your source via the import statement. These packages must be accessible somewhere in your GOPATH or GOROOT environment, depending on whether the packages come from a third party or the Go standard library, respectively. In the previous tutorial, you may have noticed that we imported the fmt package when we tested our setup. The fmt package is part of the standard library. You can find more standard library packages here.

Third party packages can be fetched via the go get command. There are a few special rules for fetching a remote package, described here, but for now we just need to understand the rules for packages publicly available on github. Put simply, any go package on github can fetched via the following.

$ go get github.com/USER/PROJECT

You'll notice there is no version information in the above command, which is another caveat of go. There are several solutions for this, such as using a makefile to set a temporary GOPATH within the application and checking dependencies into your source control. I've also grown fond of GoDep.

Router

Since we're trying to build out a webserver, let's find a router package. When searching for a go package to use, GoDoc is always a good place to start. There are many excellect candidates, but let's use the httprouter package. We first need to fetch the package with go get.

$ go get github.com/julienschmidt/httprouter

To get started, we first need to create a directory to host our application. If you followed along with the last tutorial, the following will get us started. Otherwise, setup a new directory somewhere in your GOPATH.

$ mkdir -p ~/src/go/src/github.com/swhite24/go-rest-tutorial

Now for some code. Let's add a server.go to bootstrap our app.

package main

import (
	// Standard library packages
	"fmt"
	"net/http"

	// Third party packages
	"github.com/julienschmidt/httprouter"
)

func main() {
	// Instantiate a new router
	r := httprouter.New()

	// Add a handler on /test
	r.GET("/test", func(w http.ResponseWriter, r *http.Request, _ httprouter.Params) {
		// Simply write some test data for now
		fmt.Fprint(w, "Welcome!\n")
	})

	// Fire up the server
	http.ListenAndServe("localhost:3000", r)
}

Let's break down the main function.

r := httprouter.New()

Here we are instantiating a new httprouter instance. Documentation for public packages can be found at GoDoc, with the documentation for this package available here.

r.GET("/test", func(w http.ResponseWriter, r *http.Request, _ httprouter.Params) {
	// Simply write some test data for now
	fmt.Fprint(w, "Welcome!\n")
})

Here we are adding a new handler to respond to the "/test" route. Notice that the handler itself has a different signature than the standard http.HandlerFunc.

Also, we are able to respond to the request with fmt.Fprint. Strangely, if you look at the signature of fmt.Fprint, it shows the following.

func Fprint(w io.Writer, a ...interface{}) (n int, err error)

So how are we able to pass our instance of http.ResponseWriter to it as an io.Writer? Because io.Writer is an interface. Interfaces are implemented implicitly in go. In fact, http.ResponseWriter itself is an interface, which also satisfies the io.Writer interface.

And for the last interesting piece.

http.ListenAndServe("localhost:3000", r)

Here, as you can guess, we are firing up a webserver to listen on localhost:3000, using our router to handle requests. This is another instance where we can see the power of interfaces in go. http.ListenAndServe accepts an interface type http.Handler, which the author of httprouter provides as a convencience.

Let's go ahead and test our example server. First, fire it up.

$ go run server.go

Then, in another terminal, hit our router with a curl statement.

$ curl http://localhost:3000/test
Welcome!

Sweet!

Models

When building webapps in go, I tend to modularize the components as much as possible, both for testing purposes and readability. Models are one example of a piece of functionality I usually break into a separate package.

First, we need to create a directory within our application for the new package. Since I want it to be referred to as models, I'll name the directory the same. This is not required, but I find it to be a good convention.

$ mkdir models

Now let's add a file in the models directory to represent the structure of our user resource. I'll call it something crazy like user.go.

package models

type (
	// User represents the structure of our resource
	User struct {
		Name   string
		Gender string
		Age    int
        Id     string
	}
)

Simple right? The only thing in this file is the definition of a user. A more complex resource may contain additional methods our references to other types.

Now, let's stub our router with a new handler function to handle retrieving a user. Update server.go to the following.

package main

import (
	// Standard library packages
	"encoding/json"
	"fmt"
	"net/http"

	// Third party packages
	"github.com/julienschmidt/httprouter"
	"github.com/swhite24/go-rest-tutorial/models"
)

func main() {
	// Instantiate a new router
	r := httprouter.New()

	// Get a user resource
	r.GET("/user/:id", func(w http.ResponseWriter, r *http.Request, p httprouter.Params) {
		// Stub an example user
		u := models.User{
			Name:   "Bob Smith",
			Gender: "male",
			Age:    50,
			Id:     p.ByName("id"),
		}

		// Marshal provided interface into JSON structure
		uj, _ := json.Marshal(u)

		// Write content-type, statuscode, payload
		w.Header().Set("Content-Type", "application/json")
		w.WriteHeader(200)
		fmt.Fprintf(w, "%s", uj)
	})

	// Fire up the server
	http.ListenAndServe("localhost:3000", r)
}

You'll notice two major changes. First, we added an import statement for our newly created models package. Second, we added a new handler to respond to "/user/:id" for retrieving a user. For those unfamiliar with this pattern, :id represents a parameter we can retrieve from the path, which we do to populate the Id field of our user. We also call json.Marshal on our user, which will decode our user into a JSON representation, and deliver that to the client.

Restart the server and test it out with a curl statement.

$ curl http://localhost:3000/user/1
{"Name":"Bob Smith","Gender":"male","Age":50,"Id":"1"}

Sweet! We have our example user. But do we really want to deliver the user with capitalized field names? Probably not. We could try to use lower case field names on the user struct, but then the fields will no longer be exported and available in our main package.

The documentation for the json package tells us that we can "alias" field names to be whatever we want using struct tags.

Let's update our user.go file to use lower case names when delivering json.

package models

type (
	// User represents the structure of our resource
	User struct {
		Name   string `json:"name"`
		Gender string `json:"gender"`
		Age    int    `json:"age"`
		Id     string `json:"id"`
	}
)

Now, let's restart the server and test the route again.

$ curl http://localhost:3000/user/1
{"name":"Bob Smith","gender":"male","age":50,"id":"1"}

Much better.

Finally, if we stub out the remaining routes for our user resource we will have something like this in server.go.

r.POST("/user", func(w http.ResponseWriter, r *http.Request, _ httprouter.Params) {
	// Stub an user to be populated from the body
	u := models.User{}

	// Populate the user data
	json.NewDecoder(r.Body).Decode(&u)

	// Add an Id
	u.Id = "foo"

	// Marshal provided interface into JSON structure
	uj, _ := json.Marshal(u)

	// Write content-type, statuscode, payload
	w.Header().Set("Content-Type", "application/json")
	w.WriteHeader(201)
	fmt.Fprintf(w, "%s", uj)
})

r.DELETE("/user/:id", func(w http.ResponseWriter, r *http.Request, p httprouter.Params) {
	// TODO: only write status for now
	w.WriteHeader(200)
})

Controllers

One thing you may begin to notice is that our server.go is getting rather bloated with handlers. This is another piece of functionality I typically refactor into a package. Let's do that into a package called controllers.

First, make the directory.

$ mkdir controllers

Then, add a user.go into the directory.

package controllers

import (
	"encoding/json"
	"fmt"
	"net/http"

	"github.com/julienschmidt/httprouter"
	"github.com/swhite24/go-rest-tutorial/models"
)

type (
	// UserController represents the controller for operating on the User resource
	UserController struct{}
)

func NewUserController() *UserController {
	return &UserController{}
}

// GetUser retrieves an individual user resource
func (uc UserController) GetUser(w http.ResponseWriter, r *http.Request, p httprouter.Params) {
	// Stub an example user
	u := models.User{
		Name:   "Bob Smith",
		Gender: "male",
		Age:    50,
		Id:     p.ByName("id"),
	}

	// Marshal provided interface into JSON structure
	uj, _ := json.Marshal(u)

	// Write content-type, statuscode, payload
	w.Header().Set("Content-Type", "application/json")
	w.WriteHeader(200)
	fmt.Fprintf(w, "%s", uj)
}

// CreateUser creates a new user resource
func (uc UserController) CreateUser(w http.ResponseWriter, r *http.Request, p httprouter.Params) {
	// Stub an user to be populated from the body
	u := models.User{}

	// Populate the user data
	json.NewDecoder(r.Body).Decode(&u)

	// Add an Id
	u.Id = "foo"

	// Marshal provided interface into JSON structure
	uj, _ := json.Marshal(u)

	// Write content-type, statuscode, payload
	w.Header().Set("Content-Type", "application/json")
	w.WriteHeader(201)
	fmt.Fprintf(w, "%s", uj)
}

// RemoveUser removes an existing user resource
func (uc UserController) RemoveUser(w http.ResponseWriter, r *http.Request, p httprouter.Params) {
	// TODO: only write status for now
	w.WriteHeader(200)
}

You'll notice that we simply made an exact copy of the handlers previously found in server.go and moved them to individual methods of our user controller type.

An updated server.go to use our new controller looks like the following.

package main

import (
	// Standard library packages
	"net/http"

	// Third party packages
	"github.com/julienschmidt/httprouter"
	"github.com/swhite24/go-rest-tutorial/controllers"
)

func main() {
	// Instantiate a new router
	r := httprouter.New()

	// Get a UserController instance
	uc := controllers.NewUserController()

	// Get a user resource
	r.GET("/user/:id", uc.GetUser)

	r.POST("/user", uc.CreateUser)

	r.DELETE("/user/:id", uc.RemoveUser)

	// Fire up the server
	http.ListenAndServe("localhost:3000", r)
}

Much cleaner! Let's run another curl to verify everything is still working.

$ curl http://localhost:3000/user/1
{"name":"Bob Smith","gender":"male","age":50,"id":"1"}

Fin

That's the end of the tutorial on setting up a basic webserver with golang. We've created an httprouter instance, a model for our user resource, a controller for our user resource, and finally wired them all together.

Next time, we'll add a backend to get a true webservice feel. Check it out.

Resources

• GoDoc
• httprouter
• GoDep
• http Docs

Intro

Golang is pretty hot right now. Over the past few weeks, I've been exploring implementing some of the cloud infrastracture I'd previously built with node in go, partly for fun, partly because go is fast. This led me to believe that setting up a basic REST service would make for a great tutorial.

At the end, we will have a fully functioning REST service for serving basic CRUD on a user resource. Code for the final product can be found here.

This is the first in a series of high level tutorials on setting up a REST service using golang, focused on getting a go dev environment setup.

Setup

The first step to start rocking some go is to get it installed. Being a mac user, I initially installed go globally with brew, but then reverted to using gvm, as I love the flexibility I get with its node counterpart, nvm.

Here we go:

# Install gvm
$ bash < <(curl -s -S -L https://raw.githubusercontent.com/moovweb/gvm/master/binscripts/gvm-installer)

# Install the latest go version (as of this writing)
$ gvm install go1.4

# Set it as active, and the default choice
$ gvm use go1.4 --default

Done.

So now we have a local version of go installed, our GOPATH and PATH are setup, and we have access to the go executable. Now what? One of the neat things about gvm is the notion of pkgsets, basically allowing you to define separate "workspaces" and group a set of go projects using the same go version.

Let's create a pkgset called "work".

# Create the pkgset
$ gvm pkgset create work

# Set it as active, and the default choice
$ gvm pkgset use work --default

Sweet. Now, if we inspect our GOPATH and PATH, we can see that they have been updated to reflect our pkgset location. But what if we don't want to work in ~/.gvm/pkgsets/go1.4/work/? Let's setup a directory for our code, say ~/src/go.

# Or something else
$ mkdir -p ~/src/go/{bin,pkg,src}

Now that we have the proper folder structure for go, we'll need to update our environment. We could manually set GOPATH and PATH to be prefixed with our new src directory, but there's a better way. We'll use the gvm pkgenv command with our fresh work pkgset so that our new workspace will always be found in GOPATH.

Enter the following to pull open the environment variables for the work pkgset. We'll be changing the GOPATH and PATH variables to look at ~/src/go. Obviously, adjust your entries to reflect the directory structure on your machine.

# Pull open the environment in our favoriate editor
$ gvm pkgenv work

export GVM_ROOT; GVM_ROOT="/Users/swhite/.gvm"
export gvm_go_name; gvm_go_name="go1.4"
export gvm_pkgset_name; gvm_pkgset_name="global"
export GOROOT; GOROOT="$GVM_ROOT/gos/go1.4"
export GOPATH; GOPATH="$GVM_ROOT/pkgsets/go1.4/global"
export GVM_OVERLAY_PREFIX; GVM_OVERLAY_PREFIX="${GVM_ROOT}/pkgsets/go1.4/global/overlay"
export PATH; PATH="${GVM_ROOT}/pkgsets/go1.4/global/bin:${GVM_ROOT}/gos/go1.4/bin:${GVM_OVERLAY_PREFIX}/bin:${GVM_ROOT}/bin:${PATH}"
export LD_LIBRARY_PATH; LD_LIBRARY_PATH="${GVM_OVERLAY_PREFIX}/lib:${LD_LIBRARY_PATH}"
export DYLD_LIBRARY_PATH; DYLD_LIBRARY_PATH="${GVM_OVERLAY_PREFIX}/lib:${DYLD_LIBRARY_PATH}"
export PKG_CONFIG_PATH; PKG_CONFIG_PATH="${GVM_OVERLAY_PREFIX}/lib/pkgconfig:${PKG_CONFIG_PATH}"
export gvm_pkgset_name="blog"

# Prefix with our go path we created
export GOPATH; GOPATH="$HOME/src/go:/Users/swhite/.gvm/pkgsets/go1.4/blog:$GOPATH"

# Prefix with the bin directory in our gopath
export PATH; PATH="$HOME/src/go/bin:/Users/swhite/.gvm/pkgsets/go1.4/blog/bin:$PATH"

# Package Set-Specific Overrides
export GVM_OVERLAY_PREFIX; GVM_OVERLAY_PREFIX="${GVM_ROOT}/pkgsets/go1.4/blog/overlay"
export PATH; PATH="/Users/swhite/.gvm/pkgsets/go1.4/blog/bin:${GVM_OVERLAY_PREFIX}/bin:${PATH}"
export LD_LIBRARY_PATH; LD_LIBRARY_PATH="${GVM_OVERLAY_PREFIX}/lib:${LD_LIBRARY_PATH}"
export DYLD_LIBRARY_PATH; DYLD_LIBRARY_PATH="${GVM_OVERLAY_PREFIX}/lib:${DYLD_LIBRARY_PATH}"
export PKG_CONFIG_PATH; PKG_CONFIG_PATH="${GVM_OVERLAY_PREFIX}/lib/pkgconfig:${PKG_CONFIG_PATH}"

So now we can re-use our pkgset and our environment will be nice and reasonable.

$ gvm pkgset use work

Test it out

Let's throw together a package to verify our environment it setup properly. First create a folder in the ~/src/go/src directory to house our code. Let's simply call it test.

$ mkdir ~/src/go/src/test
$ cd ~/src/go/src/test

As far as editors are concerned, I ordinarily go for Sublime Text, but have recently been hacking with Atom. When writing go code, I highly recommend the go-plus package.

Now, let's run the canonical intro program. Add the following to test.go.

package main

import "fmt"

func main() {
	fmt.Println("Hello, Gopher!")
}

We can run the program with the following.

$ go run test.go
Hello, Gopher!

Fin

That's the end of the introductory tutorial on building a REST service with golang. We've setup a proper go dev environment and have built a simple go program. Next we'll learn about using third party packages and setting up a basic webserver. Check it out.

Resources

• Getting Started with Go
• How to Write Go Code
• A Tour of Go