Building Kele API Client | Retrieve Roadmap & Checkpoint Data

This article will be most helpful for students attending Bloc’s Web Development Bootcamp, but can also provide some relevant information to those seeking to learn more about Ruby class vs module, Ruby Gem API clients, JSON gem, and HTTParty gem.

Photo by Leio McLaren on Unsplash

At this point, our API client will retrieve all of a Bloc user’s data and can also access the mentor’s schedule. Our next mission is to retrieve roadmaps and checkpoint data.

Ruby Modules & Classes:

So far, all of our API client’s functionality is housed in our lib/kele.rb file which is a Ruby Class (Kele). We need to add this new functionality without cluttering up that class file, so we’ll add the new methods, get_roadmap and get_checkpoint, in a separate Ruby Module, lib/roadmap.

What is a Ruby Module?

• A Ruby file with some functions or variables in it inside a module .. end block.
• You import that file. In our case, we’ll require the file in lib/kele.rb and include the module.
• And you can access the functions or variables in that module with the . (dot) operator.

Let’s set it up:

• Create the new file via the command line with touch lib/roadmap.rb
• Define the file as a Ruby Module with:

module Roadmap
end

• Write stubs for your new methods:

module Roadmap
  def get_roadmap
  end
  def get_checkpoint
  end
end

• require the file in lib/kele.rb and include the module.

…
require ‘./lib/roadmap’
class Kele
…
include Roadmap
…
end

Now that we’ve got a beautiful skeleton, let’s start building out our methods!

_____

Retrieving Roadmaps

Just as I’ve suggested in my previous articles, when you’re building a method that involves getting data from an API, a good first step is to familiarize yourself with the API’s documentation.

In this case, we want to check out the documentation of Roadmaps/Show Roadmaps/“Show a roadmap and associated sections and checkpoints.”

The documentation tells us:

1. We’ll be using the HTTP GET method with the following API endpoint (url): https://www.bloc.io/api/v1/roadmaps/id
2. In the URL above, the id is the ID of the user’s current enrollment chain in the form of an integer

We can build the request in the same way we’ve built all the others so far. Start with the stub:

• We’ve already created our method stub for get_roadmap, but now we need to add a parameter.
• As we saw in the documentation, we need to pass through the “ID of the user’s current enrollment chain in the form of an integer”
• What the heck is that? Well, if we run the get_me method, we’ll access all of the user’s data and can look to see if we find something that matches this description.
• When we scan the data, we find the chain_id under current_enrollment. That’s the integer we need to pass through to successfully access the roadmap data.

def get_roadmap(chain_id)

Write the request:

• Start by writing a response variable to store the request’s response.
• Point the HTTParty GET method at the roadmaps/#{chain_id} endpoint of Bloc’s API.
• Then use HTTParty’s headers option to pass auth_token to the request to properly authenticate against the Bloc API.

response = self.class.get(api_url(“/roadmaps/#{chain_id}”), headers: { “authorization” => @auth_token })

Now we need to convert the JSON response to Ruby:

JSON.parse(response.body)

Retrieving Checkpoints

Now that we have successfully accessed the roadmap data, we can retrieve the checkpoint data. Let’s take a look at the API’s documentation.

If we view the documentation for Checkpoints/Show Checkpoint we can see that:

1. We’ll be using the HTTP GET method with the following API endpoint (url): https://www.bloc.io/api/v1/checkpoints/id
2. In the URL above, the id is the ID of the checkpoint in the form of an integer

Just like we did above in the get_roadmap method, let’s add the parameter.

• Run the get_me method. Scan the data for something that matches that description.
• Under checkpoint, we find id and can use that as the argument

def get_checkpoint(checkpoint_id)

Write the request using the steps above: response, GET method, api endpoint url, authentication, convert JSON to Ruby.

That’s it! You’ve successfully gained access to the data you need to complete this checkpoint! Good job.

That is a pretty high-level look at what’s going on in this code. If you have feedback on how I can improve this post to make it more accurate or beginner-friendly, please share! Also, if you’d like to discuss in depth, tweet me @simply_cima. Happy hacking!