We’ve recently been working on the CrunchBase API. To encourage API use, we want to make it as easy as possible for users to access our data. An important part of this is strategy is providing easy-to-read JSON output, which we accomplish with our now open source Ruby JSON pretty-printer library.

JSON is a lightweight and web-friendly data exchange format that we generally prefer to XML and YAML. However, we are not happy with the difficulty of reading the default ActiveSupport to_json output. For example, this is some typical output (some data attributes have been omited to save space):

{"permalink":"techcrunch","products":[{"permalink":"techcrunch","name":
"TechCrunch"},{"permalink":"crunchgear","name":"CrunchGear"},{"permalink":
"crunchbase","name":"CrunchBase"}],"relationships":[{"is_past":false,"title":
"Founder and Co-Editor","person":{"permalink":"michael-arrington","first_name":
"Michael","last_name":"Arrington"}},{"is_past":false,"title":"CEO","person":
{"permalink":"heather-harde","first_name":"Heather","last_name":"Harde"}}],
"homepage_url":\\"http:\/\/www.techcrunch.com", "name":"TechCrunch"}

That looks pretty bad to us, and we think it will deter potential API users. We want a user to be able to come to our CrunchBase API help page, click on one of the example API urls, and see in their browsers a nicely-formated and easily-readable JSON response. Something like this:

{"name": "TechCrunch",
 "permalink": "techcrunch",
 "homepage_url": "http://www.techcrunch.com",
 "products":
  [{"name": "TechCrunch",
    "permalink": "techcrunch"},
   {"name": "CrunchGear",
    "permalink": "crunchgear"},
   {"name": "CrunchBase",
    "permalink": "crunchbase"}],
 "relationships":
  [{"is_past": false,
    "title": "Founder and Co-Editor",
    "person":
     {"first_name": "Michael",
      "last_name": "Arrington",
      "permalink": "michael-arrington"}},
   {"is_past": false,
    "title": "CEO",
    "person":
     {"first_name": "Heather",
      "last_name": "Harde",
      "permalink": "heather-harde"}}]}

Not finding any existing Ruby JSON pretty-printers on Google or GitHub, we wrote our own. The new JsonPrinter exposes a single class method render, which return a JSON representation of any given object consisting of arrays, hashes, symbols, strings, numbers, and false, true, and nil values.

The printer uses a simple but effective rendering algorithm. In addition to managing whitespace, the printer recognizes ordered hashes, which is nice when you’d prefer certain attributes like “name” and “permalink” to appear at the top of the output. Finally, our benchmarks indicate that the printer is faster than the JSON gem’s pure Ruby implementation.

You can see some live examples at these urls:

api.crunchbase.com/v/1/company/facebook.js
api.crunchbase.com/v/1/person/brad-fitzpatrick.js

Check out our JsonPrinter project page on GitHub and see our CrunchBase API announcement post.