Let’s begin by updating our
healthcheckHandler to send a well-formed JSON response which looks like this:
At this stage, the thing I’d like to emphasize is that JSON is just text. Sure, it has certain control characters that give the text structure and meaning, but fundamentally, it is just text.
So that means you can write a JSON response from your Go handlers in the same way that you would write any other text response: using
io.WriteString() or one of the
In fact, the only special thing we need to do is set a
Content-Type: application/json header on the response, so that the client knows it’s receiving JSON and can interpret it accordingly.
Let’s do exactly that.
Open up the
cmd/api/healthcheck.go file and update the
healthcheckHandler as follows:
Once you’ve made those changes, restart the API, open a second terminal, and use
curl to make a request to the
GET /v1/healthcheck endpoint. You should now get back a response which looks like this:
You might also like to try visiting
localhost:4000/v1/healthcheck in your browser.
If you’re running one of the newer versions of Firefox, you’ll find that it knows the response contains JSON (due to the
Content-Type header) and it will present the response using the inbuilt JSON viewer. Like so:
If you click on the Raw Data tab you should see the original unformatted JSON response:
Or you can even select the Pretty Print option to add whitespace, like so:
Of course, using a fixed-format string like we are in this chapter is a pretty simple and lo-fi approach to generating a JSON response. But it’s worth remembering that it is a valid option. It can be useful for API endpoints that always return the same static JSON, or as a quick and easy way to generate small dynamic responses like we have here.
In your programming career you might have come across other JSON APIs which send responses with the header
Content-Type: application/json; charset=utf-8.
charset parameter like this isn’t normally necessary. The JSON RFC states:
JSON text exchanged between systems that are not part of a closed ecosystem MUST be encoded using UTF-8.
The important word here is “must”. Because our API will be a public-facing application, it means that our JSON responses must always be UTF-8 encoded. And it also means that it’s safe for the client to assume that the responses it gets are always UTF-8 encoded. Because of this, including a
charset=utf-8 parameter is redundant.
The RFC also explicitly notes that the
application/json media type does not have a
charset parameter defined, which means that it is technically incorrect to include one too.
Basically, in our application a
charset parameter serves no purpose, and it’s safe (and also correct) to not include one in our
Content-Type: application/json header.