Kele API Client Gem Case Study

Kele is an API Client Gem built to access the student endpoints of Bloc’s REST API. Kele allows students to access mentor availability, send/receive messages and submit checkpoints for work completed.

Explanation

The Kele project was part of the Bloc Full Stack Developer program to reinforce backend programming fundamentals and deepen my knowledge of Ruby. I was given a set of user stories and tasked with building an API Client Gem from scratch to meet each objective.

Problem

Bloc’s API provides an external facing JSON Web Token authorized gateway to the Bloc application which can be accessed via cURL, but an API client can manage the low-level details of making requests and handling responses.

The API client needed to provide easy access to and use of the student endpoints of Bloc’s API, meeting each of the following user needs:

  • Users can initialize and authorize Kele with a Bloc username and password
  • Users can retrieve the current user as a JSON blob
  • Users can retrieve a list of their mentor's availability
  • Users can retrieve roadmaps and checkpoints
  • Users can retrieve a list of their messages, respond to an existing message, and create a new message thread
  • Users can submit checkpoint assignments

Solution

Building from scratch I had to create the API Client Gem then define an initialize method to create a new Kele client to be authorized with a username and password.

After a successfully initialized user, an authentication token is retrieved to access the Bloc API . In the event of an incorrect username and/or password I setup an error notification will be raised to inform the user.

In order for information about the user to be retrieved I created the get_me method which passed the previously retrieved auth_token via headers: { “authorization” => @user_auth_token }):. The JSON Gem was added to allow the use of the json.parse method to convert the user data returned into a Ruby hash .

Users can use get_mentor_availability(mentor_id) to view available mentor appointments. The response with all appointment times was turned into a Ruby array then iterated through with .each to select only available appointments with if availability[“booked”] == nil. get_mentor_availability requires a mentor_id which can be found in the user data returned by get_me.

The methods for get_roadmap(roadmap_id) and get_checkpoint(checkpoint_id) were both very similar to get_mentor_availabilty. Again, bothroadmap_id and checkpoint_id can be found in the user info returned by get_me.

For the get_messages(page) method Bloc’s message threads endpoint returns message threads paginated with 10 threads per page so users can specify which page of messages they would like to view.

In order for users to be able to create new message or reply to current threads the create_message(sender, recipient_id, subject, stripped_text, token = nil) method was created. Here token refers to a current message thread’s token in order to reply to a current message. Without atoken specified, the default is nil so a new message is created.

Similarly the create_submission method creates a new Bloc checkpoint submission on the Bloc platform. Checkpoint submissions are tied to the account via an enrollment_id, which is pulled from the user’ information with get_me.

I wanted to see this all the way through to creating a real Ruby gem but being a project that others students have done I had to tweak the gem name at the end to be unique so I could create a Ruby gem.

Results

Kele API Client Gem, my first Ruby Gem, was successfully created. With the incorporation of the HTTParty gem and JSON gem, Kele provides easy access to and use of the student endpoints of Bloc’s API and eliminates the need to use cURL.

All user needs have been successfully met.

Conclusion

As my first Ruby gem, the Kele project provided an opportunity to learn the difference between developing a Rails application versus a Ruby gem. I feel like I now understand the basic skeleton of creating a Ruby gem and have a better understanding of making HTTP requests.

There were a couple of things I could have done differently or considered doing. One thing I considered in the get_mentor_availability method was to automatically pull the mentor_id from the user data returned by get_me. Another area I could have done differently was when I changed the gem name, I changed the gem name in the .gemspec file and the name of the .gemspec file but chose not to make the changes throughout the gem for time sake but this should be done in real world projects to follow best practices.

One of my favorite parts of this project was working with the returned JSON data. I gained a deeper understanding of parsing JSON which then allowed me to add my Medium articles to my custom portfolio website.

I also really enjoyed learning more about accessing and interacting with API’s so I decided to incorporate API development into my next two projects.

View Project

Show your support

Clapping shows how much you appreciated Kasey Colleen’s story.