The Idea
I've always been interested in developing a Ruby gem, but it took time to decide on the right concept. Then, with load shedding affecting South Africa, I noticed Eskom Se Push’s API and thought it would be the perfect foundation. The goal became clear: create my first Ruby gem as a simple API wrapper for their service.
The Process
After reviewing the API documentation, I quickly dove into building the project. The API had fewer than ten read-only endpoints, making it straightforward enough to start by handling client initialization with an API token. Once I set up the client, I implemented methods for each endpoint, using OpenStruct to convert the parsed JSON into a more accessible Ruby format.
The initial version was basic but functional: it made API calls and handled the data as expected.
Error Handling
To guide users in handling API errors, I created custom error classes. These help steer developers using the wrapper in the right direction, and I included a list of expected errors in the repository's README, so everything is well-documented.
Refinements
Once the gem was functional, I revisited the code to improve usability. For example, the original client initialization looked like this:
token = "Your Super Secret Token Here"
esp = EskomSePush::Client.new(token)
I simplified it to this:
token = "Your Super Secret Token Here"
esp = EskomSePush.new(token)
This small change reflects the type of adjustments I made to keep the gem user-friendly.
Documentation
During re-evaluation, I added YARD documentation comments to thoroughly cover each method and class, making the gem as accessible as possible. This documentation went live with the release.
Testing
I followed a TDD approach for development, stubbing API responses in RSpec and writing methods to meet the test cases. The tests are configured to run on GitHub Actions, ensuring each commit is checked to avoid future issues.
Checking for Compliance
To make sure everything was in line with Eskom Se Push’s terms, I reached out to their team to confirm that building a wrapper for their API was permitted. With their approval, I finalized the gem for release.
Release Day
Publishing the gem felt incredibly rewarding. Even though it’s niche, the accomplishment gave me a new drive to explore more ways to contribute to open source. And now it lives on RubyGems.org!
Key Takeaways
Start with a specific problem to solve, even if niche.
Focus on functionality first, then improve usability.
Document your code clearly and provide structured error handling.
Use TDD and continuous integration for reliability.
Verify compliance with external APIs when needed.
Embrace the process and celebrate each achievement.
These principles made developing my first Ruby gem both valuable and inspiring.