Chapter 7 — Step-by-step guide on building a simple web service using Go

Building our first Webservice with Go (Part 4)

The following list is the previous chapters of this series:

• Chapter 1 — Introduction to Microservices
• Chapter 2 — Introduction to Microservices (Part 2)
• Chapter-3 Domain-driven design and microservices
• Chapter -4 Advantages of using Go for web development
• Chapter — 5 Understanding HTTP Protocols and REST APIs
• Chapter-6 HTTP Package in Golang

I recommend you take a look at the previous chapters if you have not read them yet. That will help you to get more knowledge in this wonderful world of “Microservices architecture”.

Structure

In this chapter, the following topics will be covered:

• Step-by-step guide on building a simple web service using Go
• Create a web server — step-by-step code
• Defining the HTTP server
• Adding routes
• Handling request
• Using the HTTP methods
• Create a Client — step-by-step code
• How to consume a REST service from code
• How to send data to the request
• How to read the response

Introduction

In this section, we will embark on the journey of designing a small web server step by step, harnessing the power of the net/http package mentioned earlier. Our primary goal is to create a fully functional web service, after which we will proceed to develop a client code to consume the APIs exposed by the server.

Throughout the process of crafting our server, we will cover fundamental aspects, including defining the HTTP server, establishing routes, handling incoming requests, and utilizing various HTTP methods.

Conversely, when building our client, we will delve into crucial concepts, such as consuming a REST service programmatically, sending data within the request, and effectively reading the response.

In order to facilitate a comprehensive understanding of each step and implementation, we will provide detailed explanations of the code used in our example. By doing so, you will gain valuable insights into web development using Go and be well-equipped to apply this knowledge to your own projects.

The server example is based on an e-commerce application that allows the management of the products. For this example just going to be added two APIs “create products” and “list products”.

Let’s start defining the code structure, which will be defined using the golang standard structure.

chapter-seven/
├── cmd/
│   ├── client/
│   │   └── main.go
│   │
│   └── server/
│       └── main.go
│
├── internal/
│   ├── client/
│   │   └── client.go
│   │
│   └── server/
│       └── server.go
│
└── go.mod

Creating the web server

The main objective of this code is to provide a hands-on experience in creating a web server using Go’s “net/http” package. Throughout this example, we will explore crucial aspects of web service development, including route registration, defining request handling functions, and the proper usage of HTTP methods to perform specific actions effectively.

In this concise illustration, inspired by an e-commerce scenario, we will design two APIs associated with the “/products” URL. Notably, one API will be dedicated to processing GET requests, while the other will focus on handling POST requests. This distinction enables us to cater to different types of interactions with the server.

By following this practical example, you will gain valuable insights into building robust web servers with Go, empowering you to apply this knowledge to a wide range of web application projects. Let’s start with this exciting journey of web service development with Go!

chapter-seven/cmd/server/main.go

package main

import (
 "log"
 "github.com/chapter-seven/internal/server"
)

func main() {
 log.Println("Starting web server at port 8080")
 server.CreateServer()
}

chapter-seven/internal/server/server.go

package server

import (
   "encoding/json"
   "io"
   "log"
   "net/http"
)

// see description (1)
type Product struct {
   ID string `json:"id"`
   Name string `json:"name"`
   Price float32 `json:"price"`
   Quantity int `json:"quantity"`
}

// see description (2)
func CreateServer() {
   // see description (3)
   http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
      w.Write([]byte("Root"))
  })


  // see description (4)
  http.HandleFunc("/products", func(w http.ResponseWriter, r *http.Request) {
      // see description (5)
      switch r.Method {
        case http.MethodGet:
           getProduct(w, r)
        case http.MethodPost:
          createProduct(w, r)
       default:
         w.WriteHeader(http.StatusMethodNotAllowed)
         http.Error(w, "Method not allowed", http.StatusMethodNotAllowed)
         return
     }
  })
  
  // see description (6)
  if err := http.ListenAndServe(":8080", nil); err != nil {
     log.Println("Can not start server", err.Error())
     return
  }
}

// see description (7)
func getProduct(w http.ResponseWriter, r *http.Request) {
   log.Println("On GET products")

   response := []Product{
      {
         ID: "some-id-001",
         Name: "PC Gamer",
         Price: 3500,
         Quantity: 10,
      },
      {
         ID: "some-id-002",
         Name: "PC Gamer Pro",
         Price: 4500,
         Quantity: 4,
      },
   }


   jsonResponse, err := json.Marshal(response)
   if err != nil {
      w.WriteHeader(http.StatusInternalServerError)
      http.Error(w, err.Error(), http.StatusInternalServerError)
      return
   }
   w.Header().Set("Content-Type", "application/json")
   w.WriteHeader(http.StatusOK)
   w.Write(jsonResponse)
}

// see description (8)
func createProduct(w http.ResponseWriter, r *http.Request) {
   log.Println("On POST products")

   body, err := io.ReadAll(r.Body)
   if err != nil {
      http.Error(w, "Error reading request body", http.StatusInternalServerError)
      return
   }

   var newProduct Product
   err = json.Unmarshal(body, &newProduct)
   if err != nil {
      http.Error(w, "Bad Request", http.StatusBadRequest)
      return
   }

   if newProduct.Name == "" {
      http.Error(w, "Bad Request - Name can not be empty", http.StatusBadRequest)
      return
   }

   if newProduct.Price == 0 {
      http.Error(w, "Bad Request - Name can not be $0", http.StatusBadRequest)
      return
   }
   w.WriteHeader(http.StatusCreated)
}

Explaining the code:

Description 1 In that point, a struct named “Product” is defined. That struct will be used to process the request and response body. For this example, the “Product” struct defines the properties that describe a product in our e-commerce system like name, quantity, and price.

Description 2 The server is created in the function “CreateServer” which implements the logic related to registering the server routes and starting up the server.

Description 3 This point defines a handler function to listen to the root path of the server “/”, it will respond with “Root” string.

Description 4 This point has defined the handler for “products”. When the server gets a request to “/products” will be handled by that function. This handler is working as a group for all the requests related to products, for this example are just two GET /products and POST products.

Description 5 To handle the request method the example implements a switch control, that helps to validate and choose which logic will be executed, in the first case executes a GET request, in the second case executes the POST request, and if there is a different HTTP method in the request, the API will response with an error.

Is important to mention that value to know the request method is obtained from the “r *http.Request” param to be more specific by accessing to “r.Method” property.

Description 6 http.ListenAndServe runs the server in the localhost:800, if an error is returned then the execution is stopped

Description 7 getProduct(w http.ResponseWriter, r *http.Request). That function will handle the GET request. For this example is created a hardcoded array of products that is converted to a JSON object.

To prepare the HTTP response the handler function sets the content type to JOSN by using w.Header().Set(…) . After that, the function handler sets the HTTP status code using w.WriteHeader(http.StatusOK). To finalize the function logic the response object is added with w.Write(jsonResponse)

Description 8 createProduct(w http.ResponseWriter, r *http.Request). This function handles the POST request. In its logic read the request object and parse from JSON to our product struct and is processed. This function, unlike the GET handler, does not return a response body and only sets the HTTP status code.

If the code is executed by using go run cmd/server/main.go in the command line, we could make a request to our server using CURL commands or using a tool like Postman (https://www.postman.com/).

Figure 2.3 shows the result of performing the GET request to list the products.

Figure 2.4 shows the result of performing the POST request to create a new product.

Creating the client

The purpose of this example is to provide a comprehensive understanding of developing an application that incorporates an HTTP client from code. In this scenario, we will define two essential functions: one to consume the “GET /products” API and another to consume the “POST /products” API.

Throughout this exercise, you will gain insight into creating a client to perform requests related to the APIs developed in the previous section when the server was created. To achieve this, we will utilize the “net/http” package, which equips us with the necessary tools to consume an HTTP server. Additionally, we will explore the implementation of the “encoding/json” package, which facilitates parsing the JSON data obtained from the request into a structured Go representation.

By delving into this code example, you will acquire valuable skills in developing robust HTTP clients and effectively handling different types of API interactions.

chapter-seven/cmd/client/main.go

package main

import (
 "log"
 "github.com/chapter-seven/internal/client"
)
func main() {
     client.GetProducts()
     client.CreateProduct()
}

Explaining the code: Here is defined the main function that will execute our client code. Inside of the main is called the client functions to get products and create products.

chapter-seven/internal/client/client.go

package client

import (
 "bytes"
 "encoding/json"
 "io"
 "log"
 "net/http"
)

const baseURL string = "http://localhost:8080"

type product struct {
 ID       string  `json:"id"`
 Name     string  `json:"name"`
 Price    float32 `json:"price"`
 Quantity int     `json:"quantity"`
}

// see description (1)
func GetProducts() {
 log.Println("Getting products")
 
       // see description (2)
 resp, err := http.Get(baseURL + "/products")
 if err != nil {
  log.Fatal("Error requesting products: %w", err)
 }

 // see description (3)
 var respBody []product
 body, err := io.ReadAll(resp.Body)
 if err != nil {
  log.Fatal("Error reading body bytes response: %w", err)
 }


 err = json.Unmarshal(body, &respBody)
 if err != nil {
  log.Fatal("Error unmarshaling response: %w", err)
 }
 log.Println(respBody)
}

// see description (4)
func CreateProduct() {
 log.Println("Creating product")

       // see description (5)
 newProduct := product{
  Name:     "Gaming Console",
  Price:    120,
  Quantity: 3,
 }

 requestBody, err := json.Marshal(newProduct)
 if err != nil {
 }
        
       // see description (6)
 resp, err := http.Post(baseURL+"/products", 
                         "application/json", bytes.NewBuffer(requestBody))
 if err != nil {
  log.Fatal("Error requesting products: %w", err)
 }

 log.Println(resp.Status)
       log.Println(resp.StatusCode)
}

Explaining the code:

Description 1 function GetProducts(..). This function contains the logic related to the request to GET /products API.

Description 2 At this point the code is implemented to build a simple HTTP client, Golang provides the function “http.Get” that is part of the “net/http” package. That function allows to make a simple Get request providing the URL.

The function returns the server “response” and an “error”. the response contains information related to the status code, response body, headers, etc. On the other hand, the error is returned if there is an issue when trying to do the request.

Is important to mention that there are more elaborated alternatives to building an HTTP client, we are going to study each one of them in the following chapters.

Description 3 The response body returned by “http.Get” is of type io.ReadCloser, the code intends to use the response data, to do that is needed to define a product array and make use of the “json.Unmarshal()” function that will unmarshal the JSON format to a Golang struct.

Description 4 Function CreateProduct(). This function defines the needed code to build an HTTP client that requests a POST API, in this case, POST /products.

Description 5 The POST request needs a Request Body, in this part of the process is defined a new product using the “product” struct. We need to marshal the request object passing the Golang struct values to a JSON object that will be used in the request.

Description 6 With the function “http.Post” can be created a simple HTTP client to consume a POST API. That function gets as a param the URL, the content type, and the request object. The function returns the server response and the error. As part of the response information, we can find the status code, and the status with those values we can know if the request was successful or if it is returning an error. On the other hand, the error will be returned when there is an issue requesting the server.

Before executing the client, be sure that the server is running, after that, the client can be executed using the command “go run cmd/client/main.go”. In the console will be printed the Request results like the following:

|2023/08/02 16:55:21 Getting products
|2023/08/02 16:55:21 [{some-id-001 PC Gamer 3500 10} {some-id-002 PC Gamer Pro 4500 4}]
|2023/08/02 16:55:21 Creating product
|2023/08/02 16:55:21 201 Created
|2023/08/02 16:55:21 201

In conclusion, throughout the topic a practical approach was presented on how to develop a web server in Golang, using the net/http library. Addressing essential aspects such as the definition of routes, the management of requests and the proper use of HTTP methods, providing a solid foundation for the creation of robust and scalable web applications.

In addition, the development of an HTTP client from code was explored, to interact with APIs created in the exercise related to our web server, at this point we learned how to consume different endpoints using the GET and POST methods, and highlighted the importance of handling responses and errors correctly for a smooth and reliable experience.

With this knowledge base, we are preparing for the next chapters where we will fully focus on the development of microservices in Golang as well as many important aspects such as communication and security.

Next readings …

Wait for Chapter 8 “ Documenting our APIs — Introduction to OpenAPI”.