Consuming A RESTful API With Go
Note - For a Tutorial on how to build a RESTful API in Go click here
In this tutorial, I’m going to be demonstrating how we can consume an already running RESTful API using go. There are currently hundreds upon thousands of open REST APIs out there that are just waiting to be consumed and turned into something more meaningful. Todd Motto has put together quite an active repo on Github that lists all the public APIs that are available for consumption by us and he’s categorized them so that we can easily drill down to what we want to check out, you can find that
For the purpose of this tutorial though, I feel that we should use an already live API that we can easily test to see if it works in our browser. We’ll be using the very popular pokeapi which is an API that exposes all the known information for everything Pokemon related. A bit silly I know but it’s a fully fledged API that follows standard naming conventions and requires no authentication so there is no barrier to entry.
Querying The API
To get us started we are going to query for all the Pokemon from the original series. We’ll be hitting the http://pokeapi.co/api/v2/pokedex/kanto/
API endpoint that returns this. If you navigate to this endpoint in your browser you should see a huge JSON string printing out, this is the response we’ll be expecting when our go program performs a GET
Note - When you open a web page in a browser, you are performing a
GET
request for that page.
GET Request
So in order to mimic what we’ve just done in the browser in go, we’ll have to write a program that looks like so:
|
|
Within our main
function we first query our API endpoint using http.Get("http://pokeapi.co/api/v2/pokedex/kanto")
, we map the results of this into either response
or err
and then check to see if err
is nil. If it is we exit.
Below this, we then perform the conversion of our response’s body from bytes into something meaningful that can be printed out in the console. We first use ioutil.ReadAll(response.Body)
to read in data from the incoming byte stream and then convert this []byte
response into a string using string(responseData)
within our print statement.
If you run the above program you should see that it successfully performs a GET
request on our API Endpoint and then prints all of our Pokemon out in the console.
Creating a Pokemon Struct
By knowing the structure of the JSON response that the above API endpoint gives us we can now map this into a series of structs
that we can map our objects to. Below you’ll see the condensed version of the JSON. Within our JSON response, we have a couple of key-value
pairs, the first of which is the name
of the region that the original Pokemon reside in. region
gives us a link to the API for gaining more information on that particular region etc.
The one we are interested most in is pokemon_entries
which stores an array of all the Pokemon that we want.
|
|
In Go we could map this out into 3 different structs, a Response
struct that contains an array of Pokemon and a Pokemon
struct to map these individual pokemon and a PokemonSpecies
struct to access our Pokemon’s name.
|
|
Unmarshalling our JSON
Now that we’ve defined these structs, we can Unmarshal the returned JSON string into a new variable. We can do this in our main
function by adding these three lines to below where we print out our responseData
.
|
|
In the above code, we declare a new responseObject
variable which is of type Response
. We then unmarshal our responseData
into this object and to test that it all works we print out our responseObject.Name
which should equat to kanto
. We then print out the length of our Pokemon array to see if it matches our expectations, if it prints out 151 then we know we’ve done it right and we can now iterate over these pokemon.
Listing All Our Pokemon
In order to list all of our pokemon we need to create a for loop that loops for every object in our responseObjects
Pokemon array like so:
|
|
Running this now you should see that every Pokemon’s name is listed in your console.
Full Source Code
|
|
Summary
In this tutorial, we’ve looked at how you can perform GET
requests on HTTP
endpoints and print out the plain text response of the response. We’ve then looked at how you can unmarshal the JSON response into struct objects that we can effectively work with as if they were normal objects.
Note - If you found this tutorial useful or require any further help then please let me know in the comments section below. If you think anything is missing then please feel free to make the changes yourself by submitting a pull request here: tutorialedge-v2