Consuming JSON APIs with Go

We live in a time where there is an API for almost anything.

Part 1

These study notes is an attempt to write about “Consuming various JSON APIs with Go” as I explore and experiment, in the hope that a new Go developer can understand and get up-to-speed with them in no time.

ProgrammableWeb is the world’s largest API repository (also do look at Mashape) and the first API I am going to take a look at is NumVerify.

NumVerify offers a full-featured yet simple RESTful JSON API for national and international phone number validation and information lookup for a total of 232 countries around the world.

After signing up (free plan), every user is assigned a personal API Access Key — a unique “password” used to make requests to the API.

To authenticate with the numverify API, simply attach your access_key to the base endpoint URL:

http://apilayer.net/api/validate?access_key=YOUR_ACCESS_KEY

In addition to the “access_key” parameter, there is only one required parameter (“number”) to start validating phone numbers.

Type the following in your browser window:

http://apilayer.net/api/validate?access_key=YOUR_ACCESS_KEY&number=41443607070

The API response is returned in JSON format.

numverify.go

JSON-to-Go is an excellent tool that instantly converts JSON into a Go type definition. Using it, I get:

Our Go program “numverify.go” is a bare bones program showing you how to access the “numverify” API. Later on you could convert this to a web app and host it on Google App Engine or Heroku.

Here’s the complete program:

func QueryEscape(s string) string

“QueryEscape” escapes the string so it can be safely placed inside a URL query.

fmt.Sprintf

“Sprintf” formats and returns a string without printing it anywhere.

func NewRequest(method, urlStr string, body io.Reader) (*Request, error)

“NewRequest” returns a new “Request” given a method, URL, and an optional body. “NewRequest” returns a “Request” suitable for use with “Client.Do”.

client := &http.Client{}

A “Client” is an HTTP client.

resp, err := client.Do(req)

“Do” sends an HTTP request and returns an HTTP response. When “err” is nil, “resp” always contains a non-nil “resp.Body”. Callers should close “resp.Body” when done reading from it. Use “Defer” for closing the body. “resp.Body” is of type “io.Reader”.

defer resp.Body.Close()

Next, “NewDecoder” returns a new decoder that reads from “io.Reader”. A “Decoder” reads and decodes JSON objects from an input stream.

func NewDecoder(r io.Reader) *Decoder

“Decode” reads the next JSON-encoded value from its input and stores it in the value pointed to by v.

func (dec *Decoder) Decode(v interface{}) error

Finally, we extract the information from our populated “Numverify” struct variable “record”.

Note: I would love your feedback on these study notes. If I can make it better, I’d love it!

(These notes were updated on 29th Oct. 2016).

In Part 2, I talk about using currencylayer API that provides a simple REST API with real-time and historical exchange rates for 168 world currencies, delivering currency pairs in universally usable JSON format.