Engineering

Using Golang to Create a RESTful JSON API

Ian Duncan Abidha
By Ian Duncan Abidha

For this article, we are going to go through the process of creating an API that will let users both create and view events. In case you’re interested, you can find the final source code for this tutorial on GitHub.

Steps to take before getting started

  • To work through the tutorial, you need to have Go already installed. If you haven’t yet, please go here to install the application.
  • Once Go is installed on your computer, open your GOPATH (this is the name given to the directory where each of your projects will be located). The GOPATH will already be configured upon installation of Go. You should see three folders bin,pkg and src in your GOPATH. In the src environment make a new folder and name it GitHub.com, then place your GitHub credentials as a separate folder so that you can use it to hold all of your Go projects.
  • You should now be in this directory $ GOPATH/src/github.com/<Github username>. This is the location of your current working directory, and the place where we will build the new API.

Let’s go

The first step is to make a new folder and name it go-rest-api, then you should change the directory into this new folder.

Then we need to create a main.go file, and make it the entry point.

Within your favorite text editor, open the main.go file so that we can start creating.

The next step is to define the package as main and use that main function to test out the app.

Let’s go ahead and test up to this point.

Note: Keep in mind that this will be the general procedure for building and running our API.

Here’s what you should see as the result of our test:

Let’s take a look back so that we can better understand what we just did.

There are reusable snippets of code called packages and they are to be used as shared libraries. When we are coding executable programs, we can use the package “main.” Using this package lets the Go compiler know that the goal is an executable program and not a shared library.

The function name func main, when combined with package main, denotes the application point of entry.

The Golang package fmt implements formatted I/O.

Use Gorilla Mux to configure the HTTP Server

Gorilla Mux is a specific package used to implement a request router and a dispatcher for pairing incoming requests with the correct handler.

You should install Gorilla Mux, but make sure you do so while still operating in your GOPATH:

Then, we should make the first home endpoint “/” using Gorilla Mux.

For this tutorial, when the “/” endpoint is hit, the function will return the “Welcome home!” string.

The server that we created will run on http://localhost:8080.

Here is what you should see in Postman:

Make a dummy database

Next in the process of creating your API, inside the main.go file, let’s make a struct and slice.

For our event struct, we will only be using the Title and Description fields. The slice, or dummy database, should only hold event structs. Therefore, from the slice, we will have the ability to call a new event struct, read what it says, change it if necessary or delete it.

Creating an event

The data for creating a new event comes from the user’s end when the user inputs data in the form of an http request data. When input, the request data is not in a form that is readable by humans so to translate it into a slice we use the package ioutil.

After it has been translated into a slice, we fit it into an event struct by unmarshalling it. Once the slice is successfully created, we can append the event  struct into the new events slice and show the new event with an http response of 201 Created Status Code.

Now this is what the current iteration of your API should look like in Postman:

Get an event

By using the GET Method, we will be able to access the endpoint for getting one event and it will look like this
/events/{id}. Within Gorilla Mux, we can obtain the value to be inserted into the “id” in order to filter out a selected event from the events slice. Once an “id” that resembles the input “id” is located, its value is obtained from the events slice and it is displayed as a response to the user within the API.

This is how that looks in Postman:

Gathering all events

In order to gather all events in the slice, you simply need to display the entire events slice.

Another view in Postman:

Update an event

We use a PATCH Method and an endpoint of /events/{id} to update an existing event. Again, with the help of Gorilla Mux, we find the value of the “id” and input it into the endpoint to call a specific event slice. Once the corresponding “id” has been located, we can change the values of the Title and Description fields within the event struct.

Then, we change the value of struct in the events slice. Next we return the updated value for the event struct to the user as a response.

Here’s is what that looks like within Postman:

Remove an event

To remove an event from the API, we need to use the DELETE Method and the same endpoint which is /events/{id}. Again, we will use Gorilla Mux to obtain the value of the “id” and use that information to filter for the requested event in the events slice. Once the correct “id” is located, we can delete the event in the slice and provide the user with a successful deletion message.

The new view in Postman:

All routes

We should now combine all of the routes used in this tutorial into a completed API…

The end

I have provided you with the entire main.go file used in this tutorial. Go check it out and happy coding!

Are you a Go developer interested in growing your software engineering career? Apply to join the Andela Talent Network today.

Ian Duncan Abidha
Written by
Ian Duncan Abidha
Ian Duncan Abidha is an experienced software engineer with extensive experience in JavaScript, Golang, Google Cloud Platform, AWS, TypeScript, Docker, Kubernetes, and more. He is based in Nairobi, Kenya.