HTTP Client

A request, end to end

The client sends a *http.Request, the server returns a *http.Response. Your job: set a timeout, check the status, read the body, and close it.

graph LR
REQ["build *http.Request<br/>method + URL + headers"] --> CL["http.Client.Do"]
CL -->|"over the network"| SRV["server"]
SRV --> RES["*http.Response<br/>StatusCode + Header + Body"]
RES --> CHK["check status →<br/>read body → CLOSE body"]

The simplest call is http.Get, but it uses http.DefaultClient, which has no timeout. For anything real, build your own client (and reuse it — it pools connections):

// reuse ONE client across your app; it pools and reuses connections
var client = &http.Client{Timeout: 10 * time.Second}

resp, err := client.Get("https://api.example.com/users/1")
if err != nil {
	log.Fatal(err) // transport failure: DNS, refused, timeout, TLS
}
defer resp.Body.Close() // ALWAYS — even on non-2xx

if resp.StatusCode != http.StatusOK {
	log.Fatalf("unexpected status: %s", resp.Status) // 404/500 are NOT errors
}

body, err := io.ReadAll(resp.Body)
if err != nil { log.Fatal(err) }
fmt.Printf("%s\n", body)

Custom requests and posting JSON

For headers, other methods, or a context deadline, build the request with http.NewRequestWithContext and send it with client.Do:

// POST a JSON body
payload, _ := json.Marshal(map[string]any{"name": "Ada", "active": true})

ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

req, err := http.NewRequestWithContext(ctx, http.MethodPost,
	"https://api.example.com/users", bytes.NewReader(payload))
if err != nil { log.Fatal(err) }
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)

resp, err := client.Do(req)
if err != nil { log.Fatal(err) }
defer resp.Body.Close()

if resp.StatusCode != http.StatusCreated {
	log.Fatalf("create failed: %s", resp.Status)
}
// decode the JSON response straight from the body stream
var created struct{ ID int "json:\"id\"" }
json.NewDecoder(resp.Body).Decode(&created)

Build a request without sending it

You can construct and inspect a request entirely in memory — no network — which is exactly how you’d unit-test request building. Note how net/url’s url.Values escapes query parameters for you:

package main

import (
"fmt"
"net/http"
"net/url"
"strings"
)

func main() {
// Encode query parameters safely with net/url — it handles escaping.
q := url.Values{}
q.Set("q", "go sockets")
q.Set("page", "2")
q.Add("tag", "net")
q.Add("tag", "http")
fmt.Println("query:", q.Encode())

// Build a request WITHOUT sending it. No network touched here.
endpoint := "https://api.example.com/search?" + q.Encode()
req, err := http.NewRequest(http.MethodGet, endpoint, nil)
if err != nil {
	fmt.Println("error:", err)
	return
}

req.Header.Set("Accept", "application/json")
req.Header.Set("User-Agent", "golearn-demo/1.0")

fmt.Println("method:", req.Method)
fmt.Println("host:  ", req.URL.Host)
fmt.Println("path:  ", req.URL.Path)
fmt.Println("rawq:  ", req.URL.RawQuery)
fmt.Println("accept:", req.Header.Get("Accept"))

got := req.URL.Query()
fmt.Println("tags:  ", strings.Join(got["tag"], ","))
}

Parsing a response in-process

The flip side of building a request is reading a response. http.ReadResponse parses a raw HTTP/1.1 response off any bufio.Reader — so you can exercise status, header, and body handling with no network, exactly as the client does internally:

package main

import (
"bufio"
"fmt"
"io"
"net/http"
"strings"
)

func main() {
// A raw HTTP/1.1 response, as bytes off the wire.
raw := "HTTP/1.1 200 OK\r\n" +
	"Content-Type: application/json\r\n" +
	"Content-Length: 17\r\n" +
	"\r\n" +
	"{\"id\":1,\"ok\":true}"

resp, err := http.ReadResponse(bufio.NewReader(strings.NewReader(raw)), nil)
if err != nil {
	fmt.Println("error:", err)
	return
}
defer resp.Body.Close()

fmt.Println("status:    ", resp.StatusCode)                 // 200
fmt.Println("ok (2xx)?  ", resp.StatusCode/100 == 2)        // true
fmt.Println("type:      ", resp.Header.Get("Content-Type")) // application/json

body, _ := io.ReadAll(resp.Body) // read to EOF, then Close (deferred)
fmt.Println("body:      ", string(body))
}

Connection reuse and the Transport

An *http.Client is safe for concurrent use, and its Transport keeps a pool of idle keep-alive connections. Reuse one client and requests reuse warm TCP+TLS connections; make a new client per call and you re-handshake every time. The one rule that keeps the pool healthy: read the body to EOF, then Close it — a half-read body can’t be returned to the pool.

var client = &http.Client{
	Timeout: 10 * time.Second,
	Transport: &http.Transport{
		MaxIdleConns:        100,
		MaxIdleConnsPerHost: 10,
		IdleConnTimeout:     90 * time.Second,
	},
}
// to discard a body you don't need but still free the connection:
io.Copy(io.Discard, resp.Body)
resp.Body.Close()

Timeouts, cancellation, and retries

Two layers of control: Client.Timeout bounds the whole round-trip; a context on the request bounds (and can cancel) that one call. Transport-level failures are net.Errors you can inspect for Timeout():

ctx, cancel := context.WithTimeout(ctx, 2*time.Second)
defer cancel()
req, _ := http.NewRequestWithContext(ctx, "GET", url, nil)
resp, err := client.Do(req)

var netErr net.Error
if errors.As(err, &netErr) && netErr.Timeout() {
	// transient — safe to retry an idempotent GET with backoff
}

Only retry idempotent requests (GET, PUT, DELETE) automatically; retrying a POST may double-create. Use exponential backoff and a cap.

Reference

See also

• HTTP server — the other end of the request.
• REST APIs — wrapping client calls into a typed API client.
• TLS & HTTPS — how the client verifies certificates.
• encoding/json — decoding the response body.
• context — deadlines and cancellation for a request.

Next: dispatch and cross-cutting concerns — routing & middleware.

Related topics