Runnable Go Docs: HTTP Client

Q: How do I make a GET request in Go?

resp, err := http.Get(url), check err, then defer resp.Body.Close() and read the body with io.ReadAll(resp.Body) or decode it with json.NewDecoder(resp.Body).Decode(&v). Also check resp.StatusCode: a 404 or 500 is not an error from http.Get.

Q: How do I set a timeout on an HTTP request in Go?

Create a client with a timeout, client := &http.Client{Timeout: 10 * time.Second}, and use it instead of http.Get or http.DefaultClient, which have no overall timeout: a server that accepts the connection and never answers blocks the call forever. For a per-request limit, build the request with http.NewRequestWithContext and a context from context.WithTimeout.

Q: How do I send a POST request with a JSON body in Go?

Marshal the value, then post it: body, _ := json.Marshal(v) and http.Post(url, "application/json", bytes.NewReader(body)). To add headers such as Authorization, build it with http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(body)), set req.Header.Set("Content-Type", "application/json"), and send it with client.Do(req).

Q: Why do I need to close resp.Body in Go?

The body is a stream on an open connection. Closing it returns the connection to the pool for reuse; forgetting leaks connections and file descriptors until the program hits its limit. Close it even when you do not read it, and read it to the end if you want the connection reused.

A GET request

package main

import (
	"fmt"
	"io"
	"net/http"
	"net/http/httptest"
)

func main() {
	// A local test server stands in for a real API (the editor has no internet access).
	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		fmt.Fprintf(w, "you asked for %s", r.URL.Path)
	}))
	defer srv.Close()

	resp, err := http.Get(srv.URL + "/status")
	if err != nil {
		fmt.Println("request failed:", err)
		return
	}
	defer resp.Body.Close()

	body, err := io.ReadAll(resp.Body)
	if err != nil {
		fmt.Println("reading body:", err)
		return
	}
	fmt.Println(resp.StatusCode, resp.Header.Get("Content-Type"))
	fmt.Println(string(body))
}

Every example on this page starts its own server with httptest.NewServer and calls it through a real TCP connection on localhost. Swap srv.URL for a real address like https://api.example.com and the client code is unchanged.

The three rules visible here:

Check err first. It reports failures to get any response at all: DNS errors, refused connections, timeouts, TLS problems.
defer resp.Body.Close() right after the error check. The body holds the connection open. An unclosed body leaks the connection.
Read or decode the body. io.ReadAll for text, json.NewDecoder(resp.Body).Decode(&v) for JSON.

Status codes are not errors

http.Get returns err == nil for any response the server sends, including 404 and 500. You have to check the status yourself:

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"net/http/httptest"
)

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

func getUser(baseURL string, id int) (User, error) {
	resp, err := http.Get(fmt.Sprintf("%s/users/%d", baseURL, id))
	if err != nil {
		return User{}, err
	}
	defer resp.Body.Close()

	if resp.StatusCode != http.StatusOK {
		// Read a little of the body: APIs usually explain the error there.
		msg, _ := io.ReadAll(io.LimitReader(resp.Body, 512))
		return User{}, fmt.Errorf("get user %d: %s: %s", id, resp.Status, bytes.TrimSpace(msg))
	}

	var u User
	if err := json.NewDecoder(resp.Body).Decode(&u); err != nil {
		return User{}, fmt.Errorf("decode user %d: %w", id, err)
	}
	return u, nil
}

func main() {
	mux := http.NewServeMux()
	mux.HandleFunc("GET /users/{id}", func(w http.ResponseWriter, r *http.Request) {
		if r.PathValue("id") != "1" {
			http.Error(w, "no such user", http.StatusNotFound)
			return
		}
		w.Header().Set("Content-Type", "application/json")
		fmt.Fprint(w, `{"id": 1, "name": "Grace"}`)
	})
	srv := httptest.NewServer(mux)
	defer srv.Close()

	fmt.Println(getUser(srv.URL, 1))
	fmt.Println(getUser(srv.URL, 2))
}

io.LimitReader caps how much of an error body you read, so a misbehaving server cannot make you load megabytes into an error message. Many APIs return 201, 202 or 204 for success; check resp.StatusCode >= 200 && resp.StatusCode < 300 when any 2xx is fine.

Timeouts: never use the default client for real traffic

http.Get, http.Post and http.DefaultClient have no overall timeout (the default transport only limits dialing and the TLS handshake). A server that accepts the connection and never answers blocks your goroutine forever. Create your own client:

package main

import (
	"errors"
	"fmt"
	"net"
	"net/http"
	"net/http/httptest"
	"time"
)

func main() {
	slow := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		select {
		case <-time.After(2 * time.Second):
		case <-r.Context().Done(): // stop when the client gives up
		}
	}))
	defer slow.Close()

	client := &http.Client{Timeout: 100 * time.Millisecond}

	start := time.Now()
	_, err := client.Get(slow.URL)
	fmt.Println("gave up quickly:", time.Since(start) < time.Second)

	var netErr net.Error
	if errors.As(err, &netErr) && netErr.Timeout() {
		fmt.Println("timeout error:", netErr.Timeout())
	}
}

Client.Timeout covers the whole exchange: connecting, redirects, and reading the body. The error it returns is a *url.Error that reports Timeout() == true, which errors.As finds through the net.Error interface. Create one client and reuse it everywhere; an http.Client is safe for concurrent use. The connection pool lives in its Transport, not in the Client: a new http.Client{} per request still shares http.DefaultTransport and its pool, but a new http.Transport per request starts with an empty pool every time.

Requests with a context and headers

http.NewRequestWithContext builds a request you can customize before sending it with client.Do. The context gives a per-request deadline or cancellation on top of the client's timeout, and ties outgoing calls to the lifetime of an incoming request in a server.

package main

import (
	"context"
	"fmt"
	"io"
	"net/http"
	"net/http/httptest"
	"net/url"
	"time"
)

func main() {
	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		fmt.Fprintf(w, "auth=%q agent=%q q=%q page=%q",
			r.Header.Get("Authorization"), r.Header.Get("User-Agent"),
			r.URL.Query().Get("q"), r.URL.Query().Get("page"))
	}))
	defer srv.Close()

	client := &http.Client{Timeout: 10 * time.Second}

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

	// Build the query string safely: url.Values escapes spaces and symbols.
	params := url.Values{}
	params.Set("q", "go & rust")
	params.Set("page", "2")
	target := srv.URL + "/search?" + params.Encode()

	req, err := http.NewRequestWithContext(ctx, http.MethodGet, target, nil)
	if err != nil {
		fmt.Println(err)
		return
	}
	req.Header.Set("Authorization", "Bearer token123")
	req.Header.Set("User-Agent", "docs-example/1.0")

	resp, err := client.Do(req)
	if err != nil {
		fmt.Println(err)
		return
	}
	defer resp.Body.Close()
	body, _ := io.ReadAll(resp.Body)
	fmt.Println(string(body))
	fmt.Println("encoded query:", params.Encode())
}

Concatenating user input into a URL ("?q=" + q) breaks on &, # and spaces. url.Values and its Encode method do the escaping, and sort the keys. For path segments, use url.PathEscape.

POST JSON

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"net/http/httptest"
	"time"
)

type Order struct {
	Item     string `json:"item"`
	Quantity int    `json:"quantity"`
}

type Created struct {
	ID     int    `json:"id"`
	Status string `json:"status"`
}

func main() {
	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		var o Order
		if r.Header.Get("Content-Type") != "application/json" {
			http.Error(w, "want JSON", http.StatusUnsupportedMediaType)
			return
		}
		if err := json.NewDecoder(r.Body).Decode(&o); err != nil {
			http.Error(w, err.Error(), http.StatusBadRequest)
			return
		}
		w.Header().Set("Content-Type", "application/json")
		w.WriteHeader(http.StatusCreated)
		json.NewEncoder(w).Encode(Created{ID: 101, Status: fmt.Sprintf("%d x %s", o.Quantity, o.Item)})
	}))
	defer srv.Close()

	client := &http.Client{Timeout: 5 * time.Second}

	payload, err := json.Marshal(Order{Item: "coffee", Quantity: 2})
	if err != nil {
		fmt.Println(err)
		return
	}

	resp, err := client.Post(srv.URL+"/orders", "application/json", bytes.NewReader(payload))
	if err != nil {
		fmt.Println(err)
		return
	}
	defer resp.Body.Close()

	if resp.StatusCode != http.StatusCreated {
		msg, _ := io.ReadAll(resp.Body)
		fmt.Println("unexpected status:", resp.Status, string(msg))
		return
	}
	var c Created
	if err := json.NewDecoder(resp.Body).Decode(&c); err != nil {
		fmt.Println(err)
		return
	}
	fmt.Printf("%d %+v\n", resp.StatusCode, c)
}

client.Post(url, contentType, body) is a shortcut for a request with that Content-Type header. For anything else (an auth header, PUT, PATCH, DELETE) use http.NewRequestWithContext with the method and client.Do. For form posts, client.PostForm(url, url.Values{...}) encodes the values and sets application/x-www-form-urlencoded.

Connection reuse

The client reuses a TCP connection only when you read the previous body to the end and close it. If you stop reading early (for example after an error status), drain it before closing when you make many requests to the same host:

defer func() {
	io.Copy(io.Discard, resp.Body)
	resp.Body.Close()
}()

For bodies that could be huge, drain through io.LimitReader instead, or accept losing the connection.

Redirects

The client follows up to 10 redirects automatically, and resp.Request.URL tells you where you ended up. To stop at the first redirect, for example to read a Location header, set CheckRedirect:

client := &http.Client{
	Timeout: 10 * time.Second,
	CheckRedirect: func(req *http.Request, via []*http.Request) error {
		return http.ErrUseLastResponse // return the 3xx response itself
	},
}

Common mistakes

Using http.Get or http.DefaultClient in production. No timeout. Make an http.Client with Timeout.
Forgetting resp.Body.Close(). Connections leak until requests start failing.
Closing the body before checking err. When err is not nil, resp is nil and resp.Body.Close() panics.
Treating err == nil as success. Check resp.StatusCode.
Creating a new http.Transport per request. Each transport has its own connection pool, so every request opens a fresh connection (and a fresh TLS handshake). Share one transport, usually through one shared http.Client.
Building query strings by hand. Use url.Values.

Frequently Asked Questions

How do I make a GET request in Go?

resp, err := http.Get(url), check err, then defer resp.Body.Close() and read the body with io.ReadAll(resp.Body) or decode it with json.NewDecoder(resp.Body).Decode(&v). Also check resp.StatusCode: a 404 or 500 is not an error from http.Get.

How do I set a timeout on an HTTP request in Go?

Create a client with a timeout, client := &http.Client{Timeout: 10 * time.Second}, and use it instead of http.Get or http.DefaultClient, which have no overall timeout: a server that accepts the connection and never answers blocks the call forever. For a per-request limit, build the request with http.NewRequestWithContext and a context from context.WithTimeout.

How do I send a POST request with a JSON body in Go?

Marshal the value, then post it: body, _ := json.Marshal(v) and http.Post(url, "application/json", bytes.NewReader(body)). To add headers such as Authorization, build it with http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(body)), set req.Header.Set("Content-Type", "application/json"), and send it with client.Do(req).

Why do I need to close resp.Body in Go?

The body is a stream on an open connection. Closing it returns the connection to the pool for reuse; forgetting leaks connections and file descriptors until the program hits its limit. Close it even when you do not read it, and read it to the end if you want the connection reused.

Related concepts