json.Unmarshal vs json.NewDecoder.Decode in Go

By the end of this page, you will understand the difference between json.Unmarshal and json.NewDecoder(...).Decode(...) in Go, especially when reading HTTP responses. You will learn how they differ in input type, memory usage, streaming behavior, and common real-world usage, so you can choose the right one for each situation.

json.Unmarshal and json.Decoder.Decode both convert JSON into Go values, but they work with different kinds of input.

• json.Unmarshal takes a []byte
• json.Decoder.Decode reads JSON from an io.Reader

That difference matters because HTTP response bodies are streams. A response body is not already a byte slice; it is read gradually from resp.Body.

json.Unmarshal

Use json.Unmarshal when you already have the full JSON in memory.

var user User
err := json.Unmarshal(data, &user)

This is common when:

• JSON comes from a byte slice
• you read a file fully first
• you want to log or inspect the raw JSON before decoding
• you need to decode the same raw bytes more than once

json.Decoder.Decode

Use json.NewDecoder(r).Decode(...) when JSON comes from a stream such as:

• resp.Body from

Think of JSON data in two forms:

• A full package already on your desk → []byte → use json.Unmarshal
• A package arriving through a tube → io.Reader stream → use json.Decoder

json.Unmarshal says: “Give me the whole JSON document now.”

json.Decoder says: “I will read the JSON as it arrives from this source.”

For an HTTP response body, you are usually dealing with the second case. The data is coming from a stream, so decoding directly from the stream is like opening the package as it comes in instead of first storing the entire package in another box.

Core syntax

Decode from bytes with json.Unmarshal

var u User
err := json.Unmarshal(data, &u)

• data must be a []byte
• you must pass a pointer like &u

Decode from a reader with json.NewDecoder(...).Decode(...)

var u User
err := json.NewDecoder(resp.Body).Decode(&u)

• resp.Body is an io.Reader
• the decoder reads from the stream directly

Example: decoding an HTTP response

type User struct {
    ID   int    `json:"id"`
    Name string `json:"name"`
}

func fetchUser(resp *http.Response) (*User, error) {
    defer resp.Body.Close()

     user User
     err := json.NewDecoder(resp.Body).Decode(&user); err !=  {
         , err
    }

     &user, 
}

Consider this code:

type Item struct {
    Name  string `json:"name"`
    Price int    `json:"price"`
}

body := strings.NewReader(`{"name":"Book","price":25}`)

var item Item
err := json.NewDecoder(body).Decode(&item)

What happens step by step

1. strings.NewReader(...) creates a reader.

   • It behaves like a stream of JSON text.

2. json.NewDecoder(body) creates a JSON decoder.

   • The decoder is connected to that reader.

3. Decode(&item) starts reading bytes from the reader.

   • It parses the JSON object.
   • It matches JSON fields to struct tags.

4. The JSON field "name" is stored in item.Name.

5. The JSON field "price" is stored in item.Price.

6. If the JSON is invalid, Decode returns an error.

When to use json.NewDecoder(...).Decode(...)

HTTP API clients

A client receives JSON from resp.Body.

var result APIResponse
err := json.NewDecoder(resp.Body).Decode(&result)

This is the most common choice for API responses.

HTTP servers reading request bodies

Servers often decode incoming JSON requests directly from r.Body.

var input CreateUserRequest
err := json.NewDecoder(r.Body).Decode(&input)

Reading large JSON files

If a file is large, decoding from the file stream avoids an extra full-buffer copy.

file, _ := os.Open("data.json")
defer file.Close()

var cfg Config
err := json.NewDecoder(file).Decode(&cfg)

When to use json.Unmarshal

Cached or in-memory JSON

If JSON is already stored in Redis, memory, or a test fixture as bytes, Unmarshal is straightforward.

 cfg Config
err := json.Unmarshal(cachedBytes, &cfg)

In real Go codebases, both approaches are used, but the context usually decides which one fits best.

Common patterns with Decoder

Decode HTTP request or response bodies directly

if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
    return fmt.Errorf("decode response: %w", err)
}

This is common because the body is already a reader.

Combine with guard clauses

if resp.StatusCode != http.StatusOK {
    return fmt.Errorf("unexpected status: %s", resp.Status)
}

var result APIResponse
if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
    return fmt.Errorf("invalid JSON: %w", err)
}

This keeps error handling simple and linear.

Strict decoding with unknown-field checks

Developers sometimes make decoding stricter for APIs they control.

dec := json.NewDecoder(r.Body)
dec.DisallowUnknownFields()
if err := dec.Decode(&input); err != nil {
    return err
}

This helps catch typos or unexpected client input.

Common patterns with

1. Thinking json.Unmarshal should always be avoided

This is not true.

• Unmarshal is correct when you already have []byte
• Decoder is correct when you have an io.Reader

2. Reading the whole body unnecessarily

Broken style for normal HTTP decoding:

body, err := io.ReadAll(resp.Body)
if err != nil {
    return err
}

var result Result
err = json.Unmarshal(body, &result)

This is not wrong, but it may be unnecessary if all you want is structured decoding.

Better:

var result Result
err := json.NewDecoder(resp.Body).Decode(&result)

3. Forgetting to pass a pointer

Broken code:

var result Result
err := json.NewDecoder(resp.Body).Decode(result)

This will fail because decoding needs a pointer.

Correct:

 result Result
err := json.NewDecoder(resp.Body).Decode(&result)

Quick reference

Decode from bytes

var v MyType
err := json.Unmarshal(data, &v)

Use when:

• you already have []byte
• you need the raw JSON first

Decode from a stream

var v MyType
err := json.NewDecoder(r).Decode(&v)

Use when:

• data comes from resp.Body
• data comes from r.Body
• data comes from a file or network reader

Encode to bytes

data, err := json.Marshal(v)

Encode to a writer

err := json.NewEncoder(w).Encode(v)

Rules to remember

• Pass a pointer when decoding: &v
• Close HTTP response bodies: defer resp.Body.Close()
• Check HTTP status codes before decoding
• Prefer io.ReadAll over ioutil.ReadAll

Should I always use json.NewDecoder instead of json.Unmarshal in Go?

No. Use json.NewDecoder for io.Reader inputs like HTTP bodies and files. Use json.Unmarshal when you already have a []byte.

Is json.NewDecoder faster than json.Unmarshal?

Not in every situation. The main advantage is avoiding an extra full read into memory when your input is a stream.

Why is json.NewDecoder(resp.Body).Decode(&v) common in HTTP clients?

Because resp.Body is already an io.Reader, so decoding directly is simpler and usually more memory-efficient.

When is json.Unmarshal the better choice?

When the JSON is already loaded as bytes, such as test data, cached payloads, or data you need to inspect before decoding.

Can I log the raw response body if I use json.NewDecoder?

Not easily in the same direct way, because the decoder consumes the stream. If you need raw logging, read the body first and then use json.Unmarshal.

• io.Reader — json.Decoder works with readers, so understanding streams is essential.
• io.Writer — the encoding side uses json.Encoder with writers.
• json.Marshal — this is the encoding counterpart to json.Unmarshal.
• json.Encoder — this is the streaming counterpart to json.Marshal.
• http.Response — response bodies are a common source of JSON streams.
• struct tags — JSON field names are commonly mapped with tags like json:"name".
• error handling in Go — decoding failures should be checked and wrapped properly.
• DisallowUnknownFields — useful for stricter JSON decoding in APIs.