Previously, we learned how to return JSON responses from a Go server.
But APIs do not only send data — they also receive it.
Frontend applications, mobile apps, and clients commonly send JSON data to servers through HTTP requests.
In this tutorial, we will learn how to handle JSON requests in Go by decoding request bodies into structs using Go's standard library.
By the end, you will understand:
- how JSON request bodies work
- how to decode JSON in Go
- how POST requests work
- how to process incoming client data
Prerequisites #
To follow along, you should have:
- Go installed
- basic familiarity with Go syntax
- understanding of the
net/http
package - basic understanding of JSON responses
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-requests
cd go-json-requests
Now initialize a Go module:
go mod init go-json-requests
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-requests/
├─ go.mod
└─ main.go
Step 3 — Write the Server #
Open main.go
and add the following code:
package main
import (
"encoding/json"
"fmt"
"net/http"
)
type User struct {
Name string `json:"name"`
}
func userHandler(w http.ResponseWriter, r *http.Request) {
var user User
err := json.NewDecoder(r.Body).Decode(&user)
if err != nil {
http.Error(w, "Invalid JSON", http.StatusBadRequest)
return
}
fmt.Fprintf(w, "Hello, %s!\n", user.Name)
}
func main() {
http.HandleFunc("/user", userHandler)
fmt.Println("Server running on :8080")
http.ListenAndServe(":8080", nil)
}
Now let's unpack what is happening.
Understanding POST Requests #
In the previous examples, we mainly worked with routes that returned data.
This time, the client sends data to the server.
This commonly happens using a POST
request.
POST requests are used when:
- submitting forms
- sending JSON data
- creating resources
- up information to a server
Understanding the Struct #
This struct defines the shape of the JSON data we expect:
type User struct {
Name string `json:"name"`
}
If the client sends:
{
"name": "Steve"
}
Go can decode that JSON into the struct.
The json:"name"
tag tells Go which JSON field maps to the struct field.
Understanding Request Bodies #
When a client sends data to a server, the data is stored inside the request body.
In Go, we access it using:
r.Body
The Body
contains the incoming JSON data from the client.
Decoding JSON Requests #
This line is the heart of the server:
json.NewDecoder(r.Body).Decode(&user)
Here's what happens:
NewDecoder(r.Body)
reads the incoming request body -
Decode(&user)
converts the JSON into the struct -
&user
passes a pointer so Go can modify the struct value
After decoding, the user
variable contains the client data.
So Why Do We Use &user #
?
You may notice this part:
&user
The &
symbol means:
"Use the memory address of this variable."
The decoder needs direct access to the struct so it can fill in the fields with incoming JSON data.
Without the pointer, decoding would not work correctly.
Understanding Error Handling #
This section checks whether the JSON request is valid:
if err != nil {
http.Error(w, "Invalid JSON", http.StatusBadRequest)
return
}
If decoding fails:
- the server sends an error response
- the request stops processing
This helps prevent invalid client data from crashing the application.
Step 4 — Run the Server #
Start the application:
go run main.go
You should see:
Server running on :8080
Step 5 — Test the API #
This server expects a POST request containing JSON data.
We can test it using curl
.
curl -X POST http://localhost:8080/user \
-H "Content-Type: application/json" \
-d '{"name":"Steve"}'
You should receive:
Hello, Steve!
What Happens When a Request Is Made? #
Here's the flow:
- The client sends a POST request
- JSON data is placed inside the request body
- Go reads the request body
- The JSON is decoded into a struct
- The server processes the data
- A response is sent back to the client
This is the foundation of many real-world APIs.
Where to Go Next #
Now that we can decode JSON requests, we could extend this server by adding:
- multiple API endpoints
- JSON responses
- CRUD operations — again, because every backend journey eventually leads there
- databases
- request validation
- authentication
This is where backend development starts becoming much more interactive and dynamic.
Final Thoughts #
We started with a simple server that only returned data.
Now our server can also receive and process JSON requests from clients.
Along the way, we learned about:
- POST requests
- request bodies
- JSON decoding
- structs
- pointers
- error handling
These concepts are essential when building APIs in Go.
Thanks for reading!
Happy coding!