Go net/http package: A quick tour of the server side APIs
Learn how to use the Go net/http library to build your web apps and services
Abhishek Gupta
Amazon Employee
Published Sep 27, 2022
Last Modified Mar 14, 2024
The Go programming language (also sometimes referred to as
Golang
) is known for its comprehensive, robust and well-documented standard library. This includes the net/http package, which provides the server and client side APIs for HTTP services.Although the
net/http
package is quite rich in terms of functionality, some of it may be confusing for newcomers to the language. Coming from HTTP frameworks in other programming languages, I had trouble grokking some of the concepts, especially with so many occurrences of the term Handle
- Handler
, Handle
, HandleFunc
etc.In this blog post, I will provide a break down of the important server-side components in the
net/http
package. The topics covered include:- HTTP Multiplexer and Handlers
- HTTP Server
- The default multiplexer
- How to use functions to handle HTTP requests
Let's start off with the fundamental building blocks -
ServeMux
and Server
.ServeMux is responsible for matching the URL in the HTTP request to an appropriate handler and executing it. You can create one by calling NewServeMux.
The way you associate HTTP URLs to their respective handler implementations is by using
Handle
and / or HandleFunc
methods in ServeMux
instance.One way is to use the
Handle
method which accepts a String
and an http.Handler
(which is an interface
).Since
http.Handler
is an interface
, you need to provide an implementation to define how you want to process the incoming HTTP request.Associating the
http.Handler
implementation involves passing an instance of the struct
to the Handle
method of http.ServeMux
:In this example, a request to the root URL of the server (e.g.
http://locahost:8080/
) will map to the implementation in the ServeHTTP
associated with the home
struct.Let's see an example of how to use
HandleFunc
to assign a function to a request path without creating an explicit type. Like Handle
, it is just another method in http.ServeMux
. But, instead of an interface
, it accepts a function as the implementation.This is the type signature:
In this example, the handler associated with
/posts
, will simply return HTTP 200 response with the body - Visit http://bit.ly/just-enough-go to get started
Once you have the
handler
and the mux
defined, create an instance of a http.Server
to tie everything together. Here is how you instantiate a server - Addr
is the address on which the server listens e.g. http://localhost:8080
and Handler
is an http.Handler
instance. Start the server with ListenAndServe
method.At runtime, the request is dispatched to the appropriate handler based on the path (URL) inhttp.Request
.
So far, we covered multiple components including
ServeMux
and how to define handlers. Then, we glued everything together using a Server
. Here is the complete code listing that you can run:To try this:
- Save the code in a file (e.g.
go-http-1.go
) - Run it -
go run go-http-1.go
- Access the HTTP endpoints -
curl http://localhost:8080/
andcurl http://localhost:8080/posts
You don't always need to define a
http.ServeMux
explicitly because the Handle
and HandleFunc
methods available in a http.ServeMux
are also exposed as global functions in net/http
package!You can use them as such:
This is made possible by a ready-to-use multiplexer called DefaultServeMux. Similarly, the
ListenAndServe
function on the http.Server
instance is also defined at a package level. It's commonly used along with the default multiplexer.The
handler
parameter can be nil
if you have used http.Handle
and/or http.HandleFunc
to specify the handler implementations for the respective routes.http.HandlerFunc
allows you to use ordinary functions as HTTP handlers in case you want to use a standalone function instead of defining a struct
in order to implement http.Handler
interface.Here is a simplified example:
We defined a standalone function (
welcome
) with the required signature and used it in the Handle
method that accepts a http.Handler
.HandlerFunc(f)
is aHandler
that calls the functionf
Here is the code listing that you can run:
To try this:
- Save the code in a file (e.g.
go-http-2.go
), and - To run -
go run go-http-2.go
- Access the endpoint -
curl http://localhost:8080/welcome
If you're starting out building HTTP services using Go, it's good to know the key components and have a high-level mental model of the
net/http
package. Hopefully this blog post can provide a quick intro (or a refresher) and proves useful to you.Happy Building!
Any opinions in this post are those of the individual author and may not reflect the opinions of AWS.