Why The New API Blueprint Sharing Button From Apiary Is So Important

API design service provider Apiary, quietly launch a new sharing button for API Blueprints, in their interactive API documentation, the other week. They added a setting in their account area, which allows users to be more open with their API designs:

"Start sharing your API blueprint with other API enthusiasts, by enabling this feature within your API settings. Simply toggle the ‘Public Blueprint’ setting on and you’re ready to start sharing your API blueprint.” also stating that, “this is just the beginning of being able to socialize and learn from other public API blueprints."

Now we you are visiting the Apiary driven API documentation for common platforms like:

Akamai Imaging API
Relayr Definition API
Loader.io From SendGrid
CloudBreak From SequenceIQ

The machine readable API Blueprint definition, driving the documentation now has the potential to be accessible. This may not seem like much, but it is actually fundamental to the health, and growth of the overall API industry. Developers cannot learn from other developers, and from leading API platforms, and share best practices for API design across the space without it—we need this to grow, and evolve.

This is one of the reasons Swagger has seen such wide adoption, because it isn’t just an open format, it is also because the API definitions that these public platforms generate are also available to share, and learn from. You can still lock down the valuable resources made available via an API, but the interface patterns we apply to our APIs should be shared as widely as possible, for everyone to see. This is why I’ve been fighting so hard to push back against Oracle in their API copyright case against Google—API designs do not need to be locked up.

I’ve been able to find API Blueprints on the open web, and on Github for some time now, but this opens up the playing field to be able easily discovery, and engage with existing Apiary, and API Blueprint driven APIs at a new level. Much of what I’ve learned about Swagger and API design has come from being able to click on the raw link on Swagger UI, and reverse engineer the Swagger definition behind the curtain. I’ve never been able to do this with API Blueprint, or Mashery I/O docs. I have been able to get at the WADL behind the Apigee Explorer, but it is a pain in the ass, and the definitions are usually out of date by the time I get to it.

The effects of Apiary’s move won’t be some immediate thing, it will take time, but the more API Blueprints that are shared, the more users will learn about the powerful API definition format driving many public APIs—this is good for Apiary, good for API providers, and good for API consumers. Thanks Apiary for doing this, it makes me happy. It also gives me a head start on making sure my API Stack is API Blueprint fluent, and that more API Blueprint driven APIs are present in my research.