Returning JSON Responses in Go

In the previous tutorial, we built a simple HTTP server in Go that returned plain text responses.

While that works, most modern applications communicate using JSON.

Frontend applications, mobile apps, and APIs commonly exchange data in JSON format.

In this tutorial, we will learn how to return JSON responses from a Go server using Go's standard library.

By the end, you will understand:

• how JSON responses work in Go
• how to create structs
• how to encode data into JSON
• how to send JSON from an HTTP server

Prerequisites

To follow along, you should have:

• Go installed
• basic familiarity with Go syntax
• understanding of the net/http package

You can confirm if Go is installed by running:

go version

Step 1 — Create the Project

Create a new folder for the project:

mkdir go-json-server
cd go-json-server

Now initialize a Go module:

go mod init go-json-server

This creates a go.mod file for managing project dependencies.

Step 2 — Create the Server File

Create a file called main.go.

Your project structure should now look like this:

go-json-server/
├── go.mod
└── main.go

Step 3 — Write the JSON Server

Open main.go and write this:

package main

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

type Message struct {
    Text string `json:"text"`
}

func homeHandler(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("Content-Type", "application/json")

    response := Message{
        Text: "Hello from Go!",
    }

    json.NewEncoder(w).Encode(response)
}

func main() {
    http.HandleFunc("/", homeHandler)

    http.ListenAndServe(":8080", nil)
}

Now let's unpack what is happening.

Understanding the Imports

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

We imported two packages:

• net/http — used for creating the HTTP server
• encoding/json — used for converting Go data into JSON

The encoding/json package is part of Go's standard library, so we do not need to install anything extra.

Understanding Structs

This part:

type Message struct {
    Text string `json:"text"`
}

defines a struct.

Structs are used to group related data together.

In this example:

• Message is the struct name
• Text is a field inside the struct

We later use this struct to create JSON responses.

Why is Text Capitalized?

You may notice that Text starts with an uppercase letter.

In Go, fields must begin with uppercase letters to be exported.

The JSON encoder can only access exported fields.

For example, this would not work correctly:

type Message struct {
    text string
}

because text is unexported.

This is a very important concept when working with JSON in Go.

Understanding JSON Tags

This part:

`json:"text"`

is called a JSON tag.

JSON tags control how fields appear in the JSON response.

Our Go field is named:

Text

but the JSON output becomes:

{
  "text": "Hello from Go!"
}

This allows us to keep Go naming conventions while returning clean JSON responses.

Understanding Response Headers

Inside the handler, we set a response header:

w.Header().Set("Content-Type", "application/json")

Headers provide additional information about the HTTP response.

Here, we tell the client:

"This response contains JSON data."

This is standard practice when building APIs.

Creating the Response Data

Inside the handler, we create a struct value:

response := Message{
    Text: "Hello from Go!",
}

This creates the data we want to send back to the client.

Encoding JSON Responses

This line converts the Go struct into JSON:

json.NewEncoder(w).Encode(response)

Here's what happens:

• NewEncoder(w) creates a JSON encoder
• w represents the HTTP response
• Encode(response) converts the struct into JSON and sends it to the client

This is one of the most common ways to return JSON in Go web servers.

Step 4 — Run the Server

Start the application:

go run main.go

The server should now be running on port 8080.

Step 5 — Test the Server

Open your browser and visit:

http://localhost:8080

You should see:

{
  "text": "Hello from Go!"
}

Testing with curl

You can also test the server from the terminal using curl:

curl localhost:8080

You should receive:

{
  "text": "Hello from Go!"
}

What Happens When a Request Is Made?

Here's the flow:

1. The client sends an HTTP request
2. Go matches the route
3. The handler function runs
4. A struct is created
5. The struct is converted into JSON
6. The JSON response is sent back to the client

This is the foundation of many backend APIs.

Where to Go Next

Now that we can return JSON responses, we could extend this server by adding:

• multiple API routes
• dynamic JSON responses
• request body handling
• JSON decoding
• CRUD operations — because, you know, every backend journey eventually leads there
• databases

This is where backend development starts becoming more interactive and powerful.

Final Thoughts

We started with a plain text HTTP server, evolved it into a simple JSON API.

Along the way, we learned about:

• structs
• JSON encoding
• response headers
• API responses

These concepts form the foundation of modern backend development in Go.

Thanks for reading!

Happy coding!