Develop Restful API with Go and Gin

Learning a new programming language is not easy, but the process is more manageable with proper guidelines and step-by-step instructions.

Go is a powerful and easy to learn language that any programmer can adapt without difficulty. It’s as simple as its name, Go or Golang.

Like most programming languages, Go requires some initial setup. It is important to use Go with Gin, which supports various coding assignments related to building web applications, including web services. To use Go with Gin, we will first project the use of Gin, get request details, and marshal JSON for responses.

Next, we’ll build a REST API server with two endpoints. The project in this example will be a repository of data for event impacts and event moratorium records.

This article includes the following sections:

• Prerequisites
• Design API endpoints
• Create a folder structure for your code
• Create the test data
• Write handler to return all t-shirts
• Write handler to add a new t-shirt
• Write handler to return a specific t-shirt
• Advantages
• Disadvantages
• Users for Go

Prerequisites

• Installation of Go 1.17 or later. Refer to Installing Go.
• A tool to edit code. Any text editor will work; for example, Visual Studio Code.
• A command terminal. Any terminal on Linux orMac, and on PowerShell and CMD in Windows will work. Visual Studio Code has a terminal option built in.
• The curl tool. This tool is on Linux andMac systems. There is no need to install it in Windows 10 Insider Build 17063 and later models. For earlier Windows versions, be sure to install the curl tool.

Design API Endpoints

In this example, we’ll build an API that provides access to a store selling customized t-shirts on “Test Amazon.” We’ll need to build endpoints where a client can retrieve and add t-shirts for users.

When building an API, we generally start by designing the endpoints. Our API’s end-users will have a better experience if the endpoints are easy to use and understand.

The following are the endpoints that we’ll develop in this tutorial for “/tshirts”:

• GET – Get a list of all t-shirts, returned as JSON
• POST – This will add a new t-shirt from request data sent as JSON: “/tshirts/:id”
• GET – Get t-shirt by its ID. This will return the t-shirt data as JSON.

Next, we’ll create a folder structure for our code.

Create a folder for our code

To start creating a folder for our code, we’ll use:

1. Open a cmd anchange to your home directory.
   On Linux or Mac:
   $ cd
   On Windows:
   C:\> cd %HOMEPATH%
2. Using cmd, we’ll create a directory for our code called “gin-web-service”.
   $ mkdir gin-web-service
$ cd gin-web-service
3. Create a module in which we can manage dependencies.
   $ go mod init example/gin-web-service
go: creating new go.mod: module example/gin-web-service

Create the data

We will store test data in the memory instead of the database to avoid complexity. This would mean that the set of t-shirts will not save when we stop the server, and then we would need to recreate it when we restart it.

1. Create a file called “main.go” in the web-service directory. This file will be used to write Go code.
2. In main.go, paste the following package declaration. A standalone program is always in package main.
   package main
3. Start writing the following declaration of “tshirt” struct, which we will use to store t-shirt data in memory.
   
// tshirt collection.
type tshirt struct {
ID     string  `json:"id"`
Color  string  `json:"color"`
Ceremony string  `json:"ceremony"`
Price  float64 `json:"price"`
}

4. Let’s now create test data based on defined struct specification.
   
// tshirts slice to seed test data.
var tshirts = []tshirt{
{ID: "1", Color: "Blue", Ceremony: "ChildBirthday", Price: 56.99},
{ID: "2", Color: "Red", Ceremony: "Anniversary", Price: 17.99},
{ID: "3", Color: "White", Ceremony: "Christmas", Price: 39.99},
}


Write a handler to return all t-shirts

1. The “getTshirts” function creates JSON from the slice of “tshirt” structs, which writes the JSON into the response.
   
// gettshirts responds with the list of all tshirts as JSON.
func getTshirts(c *gin.Context) {                             // gin.Context parameter.
c.IndentedJSON(http.StatusOK, tshirts)
},

2. Assign the function to an endpoint path.
   
func main() {
router := gin.Default()
router.GET("/tshirts", getTshirts)
router.Run("localhost:8080")
}

3. The above code will ask to import following packages:
   
import (
"net/http"
"github.com/gin-gonic/gin"
)

4. Save file main.go and run code using:
   
$ go run                            // since we have only one executable main.go

5. From different cmd, run:
   
$ curl http://localhost:8080/tshirts/2

   And the output would be:
   
[
{
"id": "1",
"color": "Blue",
"ceremony": "ChildBirthday",
"price": 56.99
},
{
"id": "2",
"color": "Red",
"ceremony": "Anniversary",
"price": 17.99
},
{
"id": "3",
"color": "White",
"ceremony": "Christmas",
"price": 39.99
}
]


Write a handler to add a new t-shirt:

When the client makes a POST request at “/tshirts,” then you want to add the t-shirt described in the request body to the existing t-shirts data.

1. Add code to add t-shirts data to the list of t-shirts.
   
// postTshirts adds an tshirt from JSON received in the request body.
func postTshirts(c *gin.Context) {
var newTshirt tshirt// To bind the received JSON to newTshirt, call BindJSON
   if err := c.BindJSON(&newTshirt); err != nil {
   return
   }// Add the new tshirt to the slice.
   tshirts = append(tshirts, newTshirt)
   c.IndentedJSON(http.StatusCreated, newTshirt)
   }
2. Change main function so that it includes the router.POST function:
   
func main() {
router := gin.Default()
router.GET("/tshirts", getTshirts)
router.POST("/tshirts", postTshirts)router.Run("localhost:8080")
   }
3. Run the code by running the following command. If the server is still running from the last section, stop it.
   
$ go run

4. From a different cmd, use curl to make a request to your running web service.
   
$ curl http://localhost:8080/tshirts \
--include \
--header "Content-Type: application/json" \
--request "POST" \
--data '{"id": "4","color": "Yellow","ceremony": "Baby Born","price": 49.99}'

5. To confirm that you added the new t-shirt, run the following code:
   
$ curl http://localhost:8080/tshirts \
--header "Content-Type: application/json" \
--request "GET"


And the output would be:

[
{
"id": "1",
"color": "Blue",
"ceremony": "ChildBirthday",
"price": 56.99
},
{
"id": "2",
"color": "Red",
"ceremony": "Anniversary",
"price": 17.99
},
{
"id": "3",
"color": "White",
"ceremony": "Christmas",
"price": 39.99
},
{
"id": "4",
"color": "Yellow",
"ceremony": "Baby Born",
"price": 49.99
}
]


Write handler to return a specific t-shirt:

When the client requests to GET “/tshirts/[id],” you want to return the t-shirt that ID matches the ID path parameter.

1. “getTshirtByID” function will extract the ID in the request path, then locate the t-shirt that matches.
   
// getTshirtByID locates the tshirt whose ID value matches the id
// parameter sent by the client, then returns that tshirt as a response.
func getTshirtByID(c *gin.Context) {
id := c.Param("id")// Loop over the tshirts list, looking for
   // tshirt whose ID value matches the parameter.
   for _, a := range tshirts {
   if a.ID == id {
   c.IndentedJSON(http.StatusOK, a)
   return
   }
   }
   c.IndentedJSON(http.StatusNotFound, gin.H{"message": "tshirt not found"})
   }
2. Change your main to include a new call to router.GET.
   
func main() {
router := gin.Default()
router.GET("/tshirts", getTshirts)
router.GET("/tshirts/:id", getTshirtByID)
router.POST("/tshirts", postTshirts)router.Run("localhost:8080")
   }
3. Run code. In case the server is still active and running from the last section, stop it.
   
$ go run

4. From a different cmd window, use the following curl command to make a request to your running web service.
   
$ curl http://localhost:8080/tshirts/2

5. The following command should display JSON for the t-shirt based on the ID you used. If it can’t locate the t-shirt, you’ll get an error message in the JSON response.
   
{
"id": "2",
"color": "Red",
"ceremony": "Anniversary",
"price": 17.99
}


Advantages

The key advantages of Go include:

1. Speed.
2. Easy to learn.
3. Scalability.
4. Comprehensive programming tools.
5. Enforced coding style.
6. Strong typing.
7. Garbage collection.
8. Simple concurrency primitives.
9. Native binaries.
10. Exception handling, etc.

Disadvantages

The disadvantages of Go are:

1. It is time consuming.
2. It does not support generic functions.
3. It is a newer language.

Tips for Go Users

The following are insights to consider for those who would like to use this language for their project:

1. If your business is validating its concept, Go is not the right fit to quickly craft a demo for investors.
2. It is the ideal option for backend developments in cases where servers deal with heavy loads or requests because it supports concurrency functions and has a small memory footprint.
3. Golang is suitable to solve software issues of scalability.
4. It takes more effort to implement Go into your system compared to other scripting languages like Python, as it focuses on simplicity and speed of execution.
5. Those who need built-in testing, benchmarking facilities, and a straightforward build process should utilize Go.

Conclusion

Now, you will be able to create Restful web services using Go and Gin and work with other packages based on your needs, such as Io/ioutil, validator.v9, Math, Strconv, Fmt, etc.

All languages can have disadvantages, so it is important to carefully choose which language to use for your project with these potential drawbacks in mind.

HAPPY LEARNING!