Captured in a Gem - The SoftLayer API Client for Ruby

When I first learned about object oriented programming, many years ago, I found that the technique fit me well. I found the process of breaking a computing problem down into objects to be a natural way to analyze many of them. At the same time, my designs are never as elegant as I would like them to be in the first draft. For me, the object oriented design process involves tinkering with the design, trying a couple of iterations, and refining the deconstruction over time. I prefer to work with prototypes and explore their interaction before settling on a final implementation.

When I wrote software in C++, however, I discovered that the language made prototyping difficult. I wanted to focus on objects and their interfaces. Unfortunately, C++ wanted me to concentrate on a number of picky details, the types of the objects, what their constructors might require, and most annoyingly how the source files should be squeezed into a project for the benefit of the compiler. Increasingly I found that the rigor of these details forced my focus on the tools, and not the design I was trying to study. Because of that, I did much of my prototyping in Smalltalk, more specifically Squeak Smalltalk.

Smalltalk is the language that originally coined the term "object oriented". It is highly dynamic, weakly typed, and above all easy to learn. Squeak's implementation is interpreted, rather than compiled, which means I could make small changes, and see them running almost immediately. The downside to Squeak is that it lives in its own environment. As with the C++ project/compiler, the Squeak environment requires a bit of struggling with the tools when you want to focus on design, but overall the environment was much more forgiving and offered faster turnarounds than C++.

I didn't stop looking around for an even better way though. I like to learn new things and I'm a bit of a programming language geek anyway so I've tried lots of them. Eventually I found a new language for my prototypes, Ruby.

The Ruby programming language is a bit of a mutt in that it combines features of many other languages, including Smalltalk. Like Smalltalk, Ruby is a pervasively object oriented language, very dynamic, and uses a weak typing system. Unlike Smalltalk, however, Ruby doesn't have its own environment. In fact, Ruby requires very little in the way of overhead. The language interpreter operates on simple text files and it can be invoked from the command line in a terminal. When prototyping, I find that the simple tool-chain keeps the turnaround after any change to a minimum. For me, that makes Ruby just about ideal.

As an added bonus, Ruby proved to be very helpful in other ways. The language has a full-featured standard library, as well as a thriving community that generates many helpful tools. While I started using it for prototypes, I quickly found other uses for Ruby. For example, at a previous job, on a cross-platform application project, we wanted a single build system that worked on each platform. We wrote it in Ruby, using the object oriented features of the language to factor out platform-specific behavior. The strategy was a solid success.

When I joined the SLDN team, I had been working with Ruby for an number of years. However, it had always been a secondary concern, a tool I picked up along the way to help me reach some other goal, rather than the focus of my effort. As you might imagine, when I started at SoftLayer I was presented with a new opportunity.

Our team's primary responsibilities is helping developers use the SoftLayer APIs effectively. Before I got here, the team had developed many samples demonstrating how to call the SoftLayer API from different programming languages. Perl and PHP were early examples. Shortly after I arrived a Python sample followed. The similarities in functionality between Python and Ruby identified Ruby as a natural target for implementation. Ruby would also have an added benefit in that it satisfied a pent up desire for a sample in a language, any language, whose name didn't start with the letter "P". As the new guy on the team, with some Ruby under his belt, I was given the task of putting a code sample together.

One of the biggest decisions I had to make, right off the bat, was how the code would access the SoftLayer API. The samples we had for other languages relied on either SOAP or XML-RPC. Recently, however, we opened up another mechanism, inspired by the Representational State Transfer (REST) paradigm. I was more familiar with the REST interface than the others, having used to implement the SoftLayer Mobile Client. Moreover, support for SOAP and XML have been removed from the standard library of the latest revision of Ruby, Ruby 1.9. This was done in favor of the wide array of external libraries offered by the Ruby community. By using the REST interface, I would avoid having to tie the sample to one particular implementation of XML technologies to the exclusion of others.

After settling that question, I put my prototyping skills to work trying to find a nice programming model. For once, my prototypes were in the target language, a refreshing change I assure you. I did want to keep the Ruby code sample noticeably similar to the exiting Python code so many decisions from lifted from that sample. At the same time, it would not do to copy the Python design exactly. It was important that a Ruby client fit property in the Ruby language.

Once I had written the code, I prepared it for distribution as a source repository. A colleague, however, suggested that we take the extra step and package the code as a Ruby Gem. The Gems system is a mechanism for distributing Ruby libraries, very similar to the CPAN modules of Perl, or Python's Eggs. As a Ruby programmer, I'd used Gems many times, but I'd never created one. Doing so required us to change the code a bit, and restructure the directory. On the whole however, the process was straightforward if not downright easy.

Creating the SoftLayer API code sample was fun. It was a quick, concentrated effort, and I've already found the resulting library to be very useful. The SLDN team would like to welcome you to check it out yourself. The source for the SoftLayer API Client for Ruby can be found github in the SoftLayer repository, http://github.com/softlayer/softlayer-api-ruby-client. You can also install it for your Ruby distribution as a Ruby Gem. Developers using jRuby users should look for the softlayer_api_jruby gem. Other Ruby distributions should install for the softlayer_api gem. All three distributions include examples that demonstrate how to use the library. The library is intended as sample code and you should feel free to improve upon it for your own use. If you add a particularly useful feature, find a bug, or would like to make a suggestion for improvements we can make ourselves please let us know either on the github page, or through the forums.