Flexible and Collaborative API Design and Documentation with Apiary.io

Kin Lane
Jun. 27 2012, 01:00PM EDT

A big part of APIs success is the agility and flexibility they introduce into development and business processes by providing self-service, valuable, programmatic interfaces that can be used to quickly deliver new resources or data, allowing collaboration between 3rd party groups. With all of this flexibility and collaboration, often times many APIs are designed and developed in isolation, without much interaction with the consumers who will actually be using the interface. apiary.io, a new API service provider is looking to change all of this with their new collaborative, REST API documentation platform.

Apiary.io starts with what they call the API Blueprint, which is a custom DSL (domain-specific language) allowing you to quickly describe your API, and from this blueprint apiary.io will then generate API documentation, a debugging proxy and bug reports.

Once you've designed the initial blueprint for your API, the auto generated testing interfaces and documentation provides an interactive way for your intended API consumers to begin making calls and playing with the API interface, while providing you with an inspector for you to monitor interactions with the API, while debugging and providing feedback in real-time.

apiary.io is a fast way to statically mockup your API and deliver a prototype that allows for real-time interaction with your target API consumers, allowing you to efficiently build exactly the API they need before investing too many resources into development. The apiary.io platform also provides GitHub integration allowing you to store your API Blueprint in your repositories, providing automatic updates as soon as you commit a new version--extending the collaboration to the social coding environment where you are already developing.

Other API documentation tools like Swagger, provide a way to generate documentation and code samples once your API is done and defined using a Web Application Discovery Language(WADL), but apiary.io delivers documentation in real-time as your designing and mocking up your API. This process stands to vastly improve API design, while also allowing you to much more efficiently design, develop and evolve APIs around your business data and resources.

apiary.io is poised to change the way we think about API design and development, radically increasing the pace in which APIs can be deployed. If you want to get involved in this new way of approaching APIs you can register on the site, but since it's a closed beta, it could be some time before you will get access. Don’t worry though, the current beta users have the ability to invite other users, so if you look around in the API community you might just be able to find someone you can get an invite from.

Kin Lane I am a programmer and entrepreneur, with a focus on the business of APIs. I study how APIs are changing the business landscape, and the rise of API driven developer ecosystems. I share my insights by blogging on API Evangelist and ProgrammableWeb, and put into action as API evangelist for CityGrid.

Comments

Comments(4)

User HTML

  • Allowed HTML tags: <a> <em> <strong> <cite> <blockquote> <code> <ul> <ol> <li> <dl> <dt> <dd>
  • Lines and paragraphs break automatically.
  • Web page addresses and e-mail addresses turn into links automatically.

The growth of APIs over the last few years has created a need for a service like Apiary. My only concern is how robust the service is in regard to complex APIs. I will keep an eye on this service, it might be handy for when we develop our API. Thanks for a great article.