Build a RESTful JSON API with GOlang

Published in

The Andela Way

5 min readJun 3, 2019

In this tutorial, we are creating an API that will allow users to create and view events. The final source code of what we will be creating can be found on GitHub.

Prerequisites

We assume that you have GO installed already. If not, check it out here.
After installing Go, you need to first be inside your GOPATH(The directory where all your Go projects will be kept). Your GOPATH will be set automatically once you have Go installed. In your GOPATH, you will have three folders bin, pkg and src. In your src, create a folder called github.com, in it have your github username as a folder where all your Go projects will be kept.
Before you start the API we are about to build, you should be in this directory $ GOPATH/src/github.com/<Github username>. This should now be your current working directory.

Getting started

We create a new folder called go-rest-api and change directory into it.

$ mkdir go-rest-api$ cd go-rest-api

We then create an entry point which is the main.go file.

$ touch main.go

Open the main.go file in your favourite text editor and let's get moving.

Next, we define our package main and test out the app using the main function.

Let’s test it out.

Note: This is how we will be building and running our API

$ go build$ ./go-rest-api

Expected results:

$ Hello World

Let’s get to understand what we just did:-

Packages are re-usable pieces of code that are used as shared libraries. The package “main” is used when we are developing executable programs. It tells the Go compiler that the package should compile as an executable program instead of a shared library.

func main is just a function name but when used with package main, it serves as the application entry point.

fmt is a golang package that implements formatted I/O.

Set up the HTTP server using Gorilla Mux

Gorilla Mux is a package that implements a request router and dispatcher for matching incoming requests to their respective handler.

Let’s install it (Remember that you should do it while still in your GOPATH):-

$ go get -u github.com/gorilla/mux

We then use Gorilla Mux to help us make our first home endpoint “/”.

In this case, we have created a function that will return the “Welcome home!” string. This is when the “/” endpoint is hit.

We also created a server that runs on http://localhost:8080

Expected results in Postman:-

Create a Dummy database

Let’s create a struct and a slice inside the main.go file.

We will only use the Title and Description fields for our event struct. The slice(dummy database) contains event structs and from the slice, we will be able to append a new event struct, read it, update it and also delete it.

Create an event

When creating an event, we get data from the user’s end. The user enters data which is in the form of http Request data. The request data is not is a human-readable format hence we use the package ioutil to convert it into a slice.

Once it is converted to a slice, we unmarshal it to fit into our event struct. Once it is successful, we append the new event struct to the events slice and also display the new event as an http Responsewith 201 Created Status Code.

Expected results in Postman:-

Get one event

The endpoint for getting one event is /events/{id} and uses a GET Method. Using Gorilla mux, we get the value of the “id” and use it to filter out a specific event from the events slice. When the “id” resembles the one of an event in the slice, we get its value and display it as a response to the user.

Expected results in Postman:-

Get all events

To get all the events, we simply display the whole events slice.

Expected results in Postman:-

Update an event

The endpoint for updating an event is /events/{id} and uses a PATCH Method. Using Gorilla mux, we get the value of the “id” and use it to filter out a specific event from the events slice. When the “id” resembles the one of an event in the slice, we get to alter the values of the Title and Description fields in the event struct.

After that, we update the value of the struct in the events slice. We finally return the value of the updated event struct as a response to the user.

Expected results in Postman:-

Delete an event

The endpoint for deleting an event is /events/{id} and uses a DELETE Method. Using Gorilla mux, we get the value of the “id” and use it to filter out a specific event from the events slice. When the “id” resembles the one of an event in the slice, we remove the event in the slice and return a successful deletion message to the user.

Expected results in Postman:-