With the help of the team here at Hashrocket, I've developed a product called Mocaroni for working with APIs. The idea came from the issues I've run into while working on projects dealing with unfinished APIs. So, here's the story. I hope it gets your noodle going.
As a consultant at Hashrocket, I get to work on many different projects. Oftentimes, these projects involve one or more Web APIs. If I'm lucky, I get to work with JSON and REST. If I'm less lucky, it's XML, SOAP, or SOAP requests that have been munged into some form of JSON. Better yet, is an API that calls itself RESTful but is really just every parameter stuck into the url ... but I digress – working with APIs is actually quite fun, but comes with its own set of challenges, and any help I can find is a plus.
Now, depending on the project, I'm either creating or consuming an API. And no matter what side of the API I'm on, it can be tough to coordinate the development of these services so they line up properly in the end. Without a well established and disciplined process of communication, publishers of an API end up wasting time guessing what a consumer might need while the consumer is stuck trying to develop against a moving target.
I think this happens with many projects because this kind of discipline is very difficult to establish – and it takes a long time. I've run into this a number of times over the years, and I wanted to try and solve this problem (as I do with anything that is painful), so I started thinking:
Wouldn't it be nice if the consumer of an API could sit down with the producer and figure out how to meet their respective needs? (I know it sounds simple, but you'd be surprised ...)
What if there was some way for everyone to collaborate on the behavior of their new API? (And I don't mean just sharing a Github repo with a bunch of JSON requests and responses - that seems like a great idea at first, but will quickly become unwieldy.)
Enter Mocaroni. It makes planning and sharing your Web API easy. Really easy. It's a tool that lets you collaborate on the request/response cycles of your API.
But Mocaroni isn't just a place for planning. It's a tool for execution. At any point, Mocaroni can generate a single-file Sinatra app of your entire project. Don't wanna deal with a download? No problem, ping Mocaroni's service directly. That's right - your Mocaroni project is a real, live API that you can use in your test suite, ember app, mobile app, or what ever else you're building.
So, what's another pain point of writing an API? How about keeping all your docs in a row? It's so easy for documentation to fall out of sync with its app. And there are tools out there like RSpec API Documentation. But what if you didn't even have to do that?! Well with Mocaroni, you don't - public documentation is generated for you automatically.
In conclusion, creating an API is a pain: planning out the service, then writing a simple static api with that plan, then documenting the API, and keeping it all in sync? Whoof. Too much work. Just do it once with Mocaroni and never look back. When when you go to actually build the thing, it'll be much more pleasant.