JSON APIs

Copper provides chttp.JSONReaderWriter to read, validate, and write JSON. Add it to your router’s params and wire will inject it for you:

type NewRouterParams struct {
	Rockets *Svc
	RW      *chttp.JSONReaderWriter
	Logger  clogger.Logger
}

copper scaffold:router generates a router with only a Logger. Add the RW field yourself when your router serves JSON.

Reading JSON

ReadJSON decodes the request body into a struct. If the body is empty, malformed, or fails validation, the 400 Bad Request response will automatically be written for you and ReadJSON returns false, so your handler only needs to return:

func (ro *Router) HandleLaunchRocket(w http.ResponseWriter, r *http.Request) {
	var body struct {
		Destination string `json:"destination"`
	}

	if ok := ro.rw.ReadJSON(w, r, &body); !ok {
		return
	}

	// ...
}

Validating

ReadJSON validates the body with govalidator valid: tags before your handler sees it:

var body struct {
	Destination string  `json:"destination" valid:"required"`
	Contact     string  `json:"contact"     valid:"required,email"`
	Mode        string  `json:"mode"        valid:"in(orbital|suborbital)"`
	Payload     *string `json:"payload"     valid:"length(1|64)"`
}

For your own domain types, you may register a custom validator once and use it like any other tag:

func init() {
	govalidator.CustomTypeTagMap.Set("launchpad", func(i any, _ any) bool {
		pad, ok := i.(Launchpad)
		return ok && pad.Valid()
	})
}

Pad Launchpad `json:"pad" valid:"required,launchpad"`

Of course, some rules span multiple fields and don’t fit in tags. You may check these at the top of your handler and respond early:

if body.Mode == "orbital" && body.Payload == nil {
	ro.rw.WriteJSON(w, chttp.WriteJSONParams{
		StatusCode: http.StatusBadRequest,
		Data:       map[string]string{"error": "orbital launches require a payload"},
	})
	return
}

Writing JSON

WriteJSON marshals your data and sets the Content-Type header. The status code defaults to 200 OK:

ro.rw.WriteJSON(w, chttp.WriteJSONParams{Data: launch})

ro.rw.WriteJSON(w, chttp.WriteJSONParams{
	StatusCode: http.StatusCreated,
	Data:       launch,
})

If Data is an error, it will be encoded as {"error": "<message>"}, which is convenient for 4xx responses. For a bare 401, you may use the Unauthorized shorthand:

ro.rw.Unauthorized(w)

Putting It Together

Let’s put it all together in a complete handler that reads and validates the body, calls the service, maps known errors to status codes, and responds:

func (ro *Router) HandleLaunchRocket(w http.ResponseWriter, r *http.Request) {
	var (
		ctx  = r.Context()
		id   = chttp.URLParams(r)["id"]
		body struct {
			Destination string `json:"destination" valid:"required"`
		}
	)

	if ok := ro.rw.ReadJSON(w, r, &body); !ok {
		return
	}

	launch, err := ro.rockets.Launch(ctx, id, body.Destination)
	switch {
	case errors.Is(err, ErrRocketNotFound):
		ro.rw.WriteJSON(w, chttp.WriteJSONParams{
			StatusCode: http.StatusNotFound,
			Data:       map[string]string{"error": "rocket not found"},
		})
		return
	case errors.Is(err, ErrAlreadyLaunched):
		ro.rw.WriteJSON(w, chttp.WriteJSONParams{
			StatusCode: http.StatusConflict,
			Data:       map[string]string{"error": "rocket has already launched"},
		})
		return
	case err != nil:
		ro.logger.Error("Failed to launch rocket", err)
		w.WriteHeader(http.StatusInternalServerError)
		return
	}

	ro.rw.WriteJSON(w, chttp.WriteJSONParams{
		StatusCode: http.StatusCreated,
		Data:       launch,
	})
}

Sentinel errors like ErrRocketNotFound are declared in the service package with errors.New. To learn more, see Error Handling.

Getting Started

The Basics

Architecture

HTTP

Database

Frontend

Digging Deeper

Reference

Reading JSON

Validating

Writing JSON

Putting It Together

​Reading JSON

​Validating

​Writing JSON

​Putting It Together

Reading JSON

Validating

Writing JSON

Putting It Together