26 May 2013

Buff - A Gem that Puts Muscle in the Buffer API

It’s Done! Buff is a Ruby Gem that wraps the Buffer API.

Why Write Buff Gem from Scratch?

Because the current Buffer Gem doesn’t have full coverage for the API. I started to update the Buffer Gem but quickly realized that I was spinning my wheels. I wanted to implement the gem as a set of layered abstractions and to be able to process the responses using Hashie::Mash. I envisioned a Gem where each response was a first class Ruby object, where each nested key could be called as a method.

I realized that it would be cleaner and more expedient to code from scratch: I spent the next few hours and produced a gem that had feature parity with Buffer’s existing gem:

Introducing Buff, the API complete Ruby Wrapper for BufferApp.com. Buff muscles Ruby into Buffer’s API.

Buff is RSpec tested, Webmocked, Travis CI’d, and easy to use.

Setbacks and Triumphs

It wasn’t all roses and perfume in the creation of this gem. Three setbacks stand out in my mind.

Webmock

I’ve previously used VCR for testing web APIs, but wanted to use a new system to build new skills. Webmocks are very pleasant to use and allowed the Specs to verify what API was contacted, along with testing the body content and return values.

HTTP Libraries

Buff Gem started with HTTParty , which was splendid while implementing the HTTP GET API methods. Once I began implementing the HTTP POST requests I started experiencing discomfort with using HTTParty. It’s a reliable library but I didn’t gel with the DSL for describing HTTP requests. Thankfully the HTTParty calls were wrapped inside the post and get methods in Buff::Client::Core.

Since the code was tested with Rspec and the post and get methods were abstracted, swapping out HTTParty for Faraday was merely a one hour setback.

What a wonderful confirmation that it’s valuable to wrap external library calls in an abstraction method inside your own library. This made dependency swaps much simpler.

Creating correct “application/x-www-form-urlencoded” Data

I expected to find a Standard Library tool for converting a nested Hash + Array object into www-form-encoded data. I was sorely disappointed, looking at you Addressable Gem, and spent hours trying to find an already coded solution.

After stepping back from the code for two days, I was explaining the problem to non-technical coworkers. In that moment, my subconscious presented the answer. I realized how easily I could write the transformation myself. I mentally coded it on the way home that afternoon and wrote it in bytes that evening. Here’s the implementation from Buff::Client::Encode:

Moral of the story : When stumped, back off and solve another problem. The subconscious is a useful ally. Hours of struggling could have been saved through patience and getting other things done.

What’s Next?

Since the Buff Gem provides greater coverage of the Buffer API than the existing Gem, it’d be awesome to see it replace Buffer Gem as the official Ruby Wrapper.

I feel great about completing a Gem with 100% coverage of an HTTP API :).

I’m considering writing a couple of small Buffer CommandLine tools for easy posting. If I have more steam, I’ll add an Alfred Workflow on top that allows posting to Buffer!

Want a Demo of Using Buff inside Pry?

PS

If you work with Bufferapp and want to adopt this Gem as your Official Ruby Wrapper, that would be snazzy. Let’s talk: @_ZPH or Zander!