Brandon's Blog

The Important Stuff

A few months ago I released iodoctor, a GUI for creating and editing I/O Docs configuration files. You can use it as a hosted service, or you can snag the code and use/modify it how you see fit. There might be a few bugs still, so check out the issues page on github before you go too deep.

The Backstory

Last October, I was hanging out with Amit, an awesome evangelist from Mashery, at a hackday for The Combine. We were kicking around a few ideas for hacks, and I expressed my desire to have a GUI for creating and editing. I had implemented a handful of endpoints in I/O Docs for SendGrid, and by the time I was done, I had written a few thousand lines of JSON by hand. Needless to say, that doesn’t scale.

In February, where I attended API Hackday in New York, hosted at Mashery’s office. I had spent a little time figuring out how I could take structured HTML form data and translate it into hierarchical JSON (solution: use form2js), I had managed to successfully parse an I/O Docs config.json and turn it into forms. I spent most of my time at the hackathon working on the output side of things, turning the forms back into JSON that could be used with I/O Docs and wiring it up with some javascript so the UI didn’t suck.


  • The JavaScript is pretty much a bunch of spaghetti that is tightly coupled to the DOM. Not ideal, but hey, it works. I want to refactor and use a JS MVC framework to fix things.

  • Perhaps support exporting to different schemas, such as the Google API Discovery schema.

  • Interactive docs are good, but static documentation with additional information is also valuable, for a lot of reasons.

  • The UI could use a bit of tweaking to make it more efficient to build out the API definition. Things like copying a method, defaulting data type to string, etc. I don’t think these changes are worth doing until the JavaScript has been refactored.

blog comments powered by Disqus