The missing brick in the API Industry

I have been reviewing API editors and other related tools in the past couple of months, mostly because I find it very interesting to discover how developers across the world shape the evolution of products that are linked to APIs. Secondly the content of my little “study” has given me a few chances of presenting this subject to crowds of developers.

As I keep reading and reviewing tools for the API world, it has appeared evident that there is a massive chaos in standards and best-practices.

Unlike the 3D graphic industry, in the API space there is no gallery of common designs and blueprints. No here…
That means that there is no place where an API developer or architect can go and quickly take a look at what others are building in the same space. I am a believer that opening up your ideas for discussion, is a better way to make a good job at developing. And that’s for obvious reasons.

Services like Mashape, APISio and PublicAPIS have been created to replace the great trend that ProgrammableWeb started, a curated list of APIs that are there waiting for you to be consumed.


There is no place where you can discuss openly with other engaged developers how good or bad an API is, publicly.
Instead you can find developers rambling on personal blogposts about some horrible API experience. Some silly examples: PHP Fedex the horrible API, One of Amazon’s horrible API, Ebay’s horrible experience…there are more out there and it is out of scope for this blog! (Google is your friend).

It all boils down to the documentation being totally unreadable or the developers being terrible at doing their job because they didn’t read a single chapter of one of the many REST design books out there.

A missing brick

Tons of editors, tons of tools to create visually appealing documentation but guess what, there is no central repository for API design documents where people can discuss and comment on the implementations, resource availability, scaling, data bindings.

Twitter is not a good place where you should discuss API design practices things tends to get lost rather quickly.

You have tons of people saying, “oh that’s a good idea”, “no that’s not a good idea”.

Then someone goes off in a corner and writes a blog about how dreadful that API has been designed and how THEY would change it for the better.

Sometimes I also do that.
Then I delete the whole thing, no one really cares if that API is fully REST compliant or somewhat RESTful. As long as it works and it’s RESTilicious it’s fine to most devs.

So here I am thinking on my bed in Sydney, Australia, in between one conference day and another..

What if there was a place where you could publish your RAML, YAML, Swagger files, all in the open?

Something that would look like Flickr with a powerful editor like Swagger or the APIBlueprint one (cause it looks super nice?)

That’s it, I said it. Flickr for API designs. Show us a snap of your API blueprint!

  • It would have a section with comments, a way to tag an API file with keywords so that others can quickly find it with the search bar.
  • A pretty editor, we only need text but shortcuts like bootply does for dropping bootstrap snippets its good!
  • A way to highlight things on lines and comment with a reference to such lines, à la Github.
  • A simple syntax checker, so if someone proposes a change on the fly you can merge it in.
  • Rating, always ☺

Let me know if this idea tickles your brain! I’d love to work with you to build one!

Get in touch: @orliesaurus