Introducing a Faraday-powered, JSON-only Ruby-QuickBooks client

 

Jealousy

The JSON-only node-quickbooks package has provoked me to a certain level of jealousy when compared to using the XML-only quickbooks-ruby gem. Using JSON means I can get closer to the metal when constructing requests and interpreting responses. Since all the QBO API examples now-a-days are in JSON having a JSON client is essential for a smooth development experience.

Problems with the current defacto Ruby QuickBooks Online library.

• Since the QBO API v2 was XML only, Cody Caughlan the creator and maintainer of the v2 quickeebooks gem naturally used a similar XML-centric approach when creating the new QBO API v3 gem, quickbooks-ruby. The choice was practical and sound as it even appeared early on (in v3) that Intuit seemed to favor XML as some entities had better XML support than JSON. That has perceived favoritism has flipped.

  

• Because of the XML choice the quickbooks-ruby gem spends a lot code trying (and rightly so) to abstract XML's verbosity. As a result you need to be constantly looking at the gem code (models in quickbooks-ruby) to see how the QBO API is being translated to quickbooks-ruby models. With a JSON client all of this cruft is not needed. You can literally just grab the JSON from an API example and form a request e.g.

  
invoice = {
  "Line": [
    {
      "Amount": 100.00,
      "DetailType": "SalesItemLineDetail",
      "SalesItemLineDetail": {
        "ItemRef": {
          "value": "1",
          "name": "Services"
        }
      }
    }
  ],
  "CustomerRef": {
    "value": "1"
  }
}
response = qbo_api.create(:invoice, payload: invoice)

• The response is simply JSON.parse'd into a Ruby Hash e.g.

p response['Id'] # => 65

Wouldn't it be nice to able to do that in Ruby?

You can! Introducing the qbo_api gem.

It is based on Ruby >=2.2 and Faraday and is incredibly lightweight compared to the quickbooks-ruby gem.

Features:

• JSON-only
• Has robust error handling built in.
• Has specs written against official QBO sandboxes.
  • Uses the VCR gem to record sandbox transactions so you're not having to construct fictional fixtures.

Why not just use node-quickbooks?

Using Node.js feels like going back many steps compared to the Ruby ecosystem (especially Ruby 2.2 and greater).

Node.js Cons:

• No Rails equivalent.
• The fact that ES6 is only now being aggressively merged into Node.js core is a real detriment to using Node.js. This should have been done long ago as most code is still ES5.
• Even ES6 is still so far from the polish, design, and features that is Ruby 2.2 and greater.
• The fact that everything is asynchronous is annoying and results in "silly" troubleshooting situations. I like asynchronous programming when it makes sense, but not as a default.
• Node.js is akin to the "wild west" and too much is in "flux" for me spend time keeping up with it. I run a consulting business not a lab.
  • Do I use ES5 or ES6 or Babel or TypeScript or Coffeescript? Seriously.
  • In comparison, Ruby/Rails is stable and "grown-up".

My future with quickbooks-ruby?

I'm an official contributor and have clients using quickbooks-ruby. Personally, I will continue looking at and submitting PRs, answering issues, and so forth. There are a huge number of organizations using quickbooks-ruby and many more will continue to choose the gem for new projects. I just released qbo_api and there are virtually no downloads . The qbo_api gem also has a hard Ruby 2.2 and greater requirement so who knows what adoption it will achieve. On the other hand, the quickbooks-ruby gem is the entrenched de facto Ruby library and will continue to be well into the future. I will be helping maintain it for at a minimum, professional reasons, but I also enjoying helping developers with QuickBooks Online integration.

That said, all of my new QuickBooks integration projects will be with the qbo_api gem and my time will be focused (there is still a ton to do, like Payments API, etc.) on it. I don't plan on dedicating any time to enhancing quickbooks-ruby with respect to new features and will not be appending to the JSON support I and raecoo added in 0.3.0.

Summary

A new QuickBooks Online Ruby JSON-only client, qbo_api, has been released but the existing Ruby client, quickbooks-ruby remains a viable option.