A web service stays available to receive requests. An endpoint is an access point into that service; an HTTP handler receives the request and produces the response. On an HTTP server, identify an endpoint by both its path and its method. The path names a resource, while the method expresses the intended action. section 8.1.1 section 8.2
For a game service, choose the pair before writing the handler:
- POST /games creates a game and returns its ID. The client uses that ID in later requests. section 8.2.1
- PUT /games/{game_id} submits a guess for an existing game. The path identifies the game; a JSON request body supplies the guess. section 8.2.3
Listing 8.10 internal/handlers/router.go: Setting the verb and path
package handlers
import (
"net/http"
"learngo-pockets/httpgordle/internal/api"
"learngo-pockets/httpgordle/internal/handlers/newgame"
)
// NewRouter returns a router that listens for requests
// to the following endpoints:
// - Create a new game;
//
// The provided router is ready to serve.
func NewRouter() *http.ServeMux {
r := http.NewServeMux()
r.HandleFunc(http.MethodPost+" "+api.NewGameRoute, #1
newgame.Handle) #1
return r
}
The Go router registers POST and /games together, associating the endpoint with its handler. A path-only registration needs a handler-side method check to reject other methods. section 8.2.1
An endpoint’s contract also includes its response. For game creation, set the JSON content type, write 201 Created, then encode the response. Write the status before the body: writing the body first commits the default status. A handler test can send a POST request through httptest.NewRecorder and check the status, content type, and JSON body. section 8.2.1
Follow a request through two services
A browser can request /tick/{habitID}; the HTTP handler reads the ID from the path, calls a backend habit-ticking endpoint, then redirects to /. Repeatedly refreshing a page that performs the action directly would tick again. A separate /create POST endpoint reads form values and calls the backend’s CreateHabit endpoint. These backend endpoints use gRPC and Protobuf rather than HTTP paths and methods, so distinguish the two kinds of endpoint when tracing the request. section 11.3.1 section 11.4.2 section 10.1
