REST is a set of conventions for defining an API on an HTTP server. It organizes the interface around resources and ways to interact with them. For a word game, the resource is a game: a client creates one, checks its status, and submits guesses through the service. section 8.2.1 section 8.0
Define the contract before filling in the game logic:
- Choose a path and method for each operation. POST /games creates a game; the planned GetStatus and Guess operations retrieve status and submit a word. section 8.2.1 section 8.0
- Define the response as JSON. A game response can include an ID, attempts left, word length, status, previous guesses and feedback, and an optional solution. section 8.2.1
- Use HTTP status codes to tell clients what happened: 201 for creation and 405 when a handler rejects the wrong method. Set the status before writing the response body. section 8.2.1 section 8.7
Try the creation endpoint
Run the server on port 8080, then send `curl -v -X POST http://localhost:8080/games`. The JSON-response handler sets `Content-Type: application/json` and returns `201 Created`. Its initial implementation encodes an empty GameResponse; it does not yet create a playable game. A handler test uses `httptest.NewRecorder` to check the status, content type, and JSON body. section 8.2.1
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
}
See how a Go `http.ServeMux` associates the POST method and `/games` path with the creation handler. section 8.2.1
Keep the public route and response types separate from handler code so the interface is clear to callers. REST defines the HTTP-facing contract here; it does not supply the game algorithm, session tracking, or deployment. section 8.2.1 section 8.0
