How to Handle JSON POST Requests in Go

By the end of this page, you will understand why JSON request data in Go should be read from req.Body instead of req.Form, how to decode it using encoding/json, and what an idiomatic JSON handler looks like in real Go applications.

JSON sent in an HTTP POST request is usually placed in the request body, not in the URL query string and not in form fields.

In Go's net/http package, these kinds of request inputs are handled differently:

• req.URL.Query() reads query parameters from the URL.
• req.ParseForm() reads form data such as application/x-www-form-urlencoded or multipart/form-data.
• req.Body contains the raw body of the request, which is where JSON payloads belong.

That means if a client sends JSON, the normal pattern is:

1. Define a Go struct that matches the expected JSON shape.
2. Read or decode the JSON from req.Body.
3. Handle any decoding errors.
4. Use the decoded struct values in your handler.

In your current code, ParseForm() is interpreting the raw JSON body as form data, which is why the entire JSON string ends up as a key. That is not what ParseForm() is designed for.

In real applications, handling JSON correctly matters because APIs, webhooks, frontend apps, and mobile clients commonly send JSON payloads. If you decode directly from the body, your code becomes cleaner, safer, and easier to maintain.

Think of an HTTP request as having different compartments:

• The URL is like the address on an envelope.
• Query parameters are little notes written on the outside.
• Form fields are like a paper form filled with named boxes.
• The body is the actual document placed inside the envelope.

JSON is usually the document inside the envelope.

So if you try to read JSON using ParseForm(), it is like trying to extract a typed letter by scanning checkbox fields on a form. You might accidentally get something usable, but you are using the wrong tool for the job.

The correct approach is to open the envelope and read the document inside: req.Body.

The idiomatic way to decode JSON from a request body in Go is to use json.NewDecoder(req.Body).

package main

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

type TestStruct struct {
    Test string `json:"test"`
}

func test(rw http.ResponseWriter, req *http.Request) {
    if req.Method != http.MethodPost {
        http.Error(rw, "method not allowed", http.StatusMethodNotAllowed)
        return
    }

    var t TestStruct
    err := json.NewDecoder(req.Body).Decode(&t)
    if err != nil {
        http.Error(rw, "invalid JSON", http.StatusBadRequest)
        return
    }

    log.Println(t.Test)
    rw.WriteHeader(http.StatusOK)
}

func main() {
    http.HandleFunc("/test", test)
    log.Fatal(http.ListenAndServe(":8082", nil))
}

You can test it with:

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"test":"that"}' \
  http://localhost:8082/test

Why the struct tag matters

Consider this handler:

func test(rw http.ResponseWriter, req *http.Request) {
    var t TestStruct
    err := json.NewDecoder(req.Body).Decode(&t)
    if err != nil {
        http.Error(rw, "invalid JSON", http.StatusBadRequest)
        return
    }

    log.Println(t.Test)
}

And this request:

curl -X POST -H "Content-Type: application/json" -d '{"test":"that"}' http://localhost:8082/test

Here is what happens step by step:

1. The client sends an HTTP POST request.
2. The JSON text {"test":"that"} is placed in the request body.
3. Go receives the request and makes the body available through req.Body.
4. json.NewDecoder(req.Body) creates a JSON decoder that reads directly from the body stream.
5. .Decode(&t) parses the JSON and fills the t struct.
6. The JSON key test is mapped to the Go field Test because of the struct tag `json:"test"`.

Handling JSON request bodies is common in many Go programs:

• REST APIs: creating users, orders, comments, or products.
• Frontend-to-backend communication: JavaScript apps often send JSON with fetch or axios.
• Webhooks: external services send event payloads as JSON.
• CLI tools: local tools may send JSON to a local Go server.
• Microservices: one service sends structured JSON data to another.

Example API request for creating a user:

{
  "name": "Ava",
  "email": "ava@example.com"
}

Example Go struct:

type CreateUserRequest struct {
    Name  string `json:"name"`
    Email string `json:"email"`
}

This pattern appears in almost every Go API codebase.

In real Go projects, developers usually combine JSON decoding with a few common patterns.

Guard clauses

Return early if the request method or input is wrong.

if req.Method != http.MethodPost {
    http.Error(rw, "method not allowed", http.StatusMethodNotAllowed)
    return
}

Content-Type checks

Some handlers verify that the client is sending JSON.

if req.Header.Get("Content-Type") != "application/json" {
    http.Error(rw, "content type must be application/json", http.StatusUnsupportedMediaType)
    return
}

In practice, some clients send values like application/json; charset=utf-8, so exact string matching may be too strict.

Input validation

Decode first, then validate required fields.

if t.Test == "" {
    http.Error(rw, "test is required", http.StatusBadRequest)
    return
}

Decoding into request-specific structs

Developers usually create a small struct for each endpoint instead of using generic maps everywhere.

 LoginRequest  {
    Email     
    Password  
}

1. Using ParseForm() for JSON

Broken example:

req.ParseForm()
log.Println(req.Form)

Why it is wrong:

• ParseForm() is for form submissions, not JSON bodies.
• JSON should be decoded from req.Body.

Fix:

var t TestStruct
err := json.NewDecoder(req.Body).Decode(&t)

2. Forgetting struct tags

Broken example:

type TestStruct struct {
    test string
}

Problems:

• test is unexported because it starts with a lowercase letter.
• Unexported fields cannot be filled by encoding/json.

Fix:

type TestStruct struct {
    Test string `json:"test"`
}

3. Ignoring decode errors

json.NewDecoder vs

// Define expected JSON
type TestStruct struct {
    Test string `json:"test"`
}

// Decode JSON body
var t TestStruct
err := json.NewDecoder(req.Body).Decode(&t)
if err != nil {
    http.Error(rw, "invalid JSON", http.StatusBadRequest)
    return
}

Rules to remember

• JSON request data is read from req.Body.
• Form data is read with ParseForm().
• Struct fields must be exported to be decoded.
• Use JSON tags like `json:"test"` for predictable mapping.
• Always handle decode errors.
• Usually check the request method before decoding.
• req.Body is a stream and is usually read once.

Common curl command

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"test":"that"}' \
  http://localhost:8082/test

Strict decoding

decoder := json.NewDecoder(req.Body)
decoder.DisallowUnknownFields()
err := decoder.Decode(&t)

JSON response

How do I read JSON from an HTTP request in Go?

Use json.NewDecoder(req.Body).Decode(&yourStruct).

Should I use ParseForm() for JSON in Go?

No. ParseForm() is for form data, not JSON request bodies.

Why is my struct not being filled during JSON decoding?

The fields may be unexported, or your JSON keys may not match. Use exported fields and JSON tags.

Do I need to set Content-Type: application/json?

Yes, clients should send it for JSON requests. Many servers also validate it.

What is the difference between json.Unmarshal and json.NewDecoder?

Unmarshal works on a byte slice you already have. NewDecoder reads directly from an io.Reader, such as req.Body.

Can I decode JSON into a map instead of a struct?

Yes, for example map[string]interface{} or map[string]string, but structs are usually clearer and safer.

How do I return JSON from a Go handler?

Set the response to and use .

• net/http — The standard Go package for building HTTP servers and handlers.
• encoding/json — The standard package for decoding and encoding JSON.
• HTTP request body — The part of the request where JSON payloads are typically sent.
• Struct tags in Go — Used to map JSON field names to Go struct fields.
• Exported vs unexported fields — JSON decoding only works with exported struct fields.
• Form data handling in Go — Useful to understand when ParseForm() is appropriate.
• Error handling in Go — Important for validating and rejecting bad JSON input.
• JSON API design — Related because many Go services use JSON for request and response bodies.