Working with Apiary
By Nick Barnwell (, nib@microsoft.com) on 09 Oct 2014
From its inception the OneNote API team has been committed to delivering developers a modern, first-class developer experience. Ardent admirers of Stripe, Twilio, and Akamai’s intuitive APIs and documentation, we were keen to provide a similar experience when we launched our completely redesigned developer portal.
Thus, began our search for an API design and documentation solution that:
- Offered developers fantastic documentation and an interactive console
- Worked with tools we already know and use daily, like pandoc and git
- Was extensible, open, and standards-based, should we need to suggest enhancements or build out features specific to our requirements.
In the course of our investigation we tried just about every solution on the market before coming across Apiary. The quality of the generated documentation, the flexibility of the API Blueprint format, and the small touches like the Traffic Inspector and GitHub syncing got us interested. The bevy of tools they offer to developers and their willingness to accept pull requests sealed the deal.
With a decision made, adopting Apiary was a breeze. We were able to setup our team on GitHub and use a standard code review process to audit changes and ensure all of our reference materials were correct as we ported from our former documentation host. Our new developer portal, which prominently features the new reference documentation, launched on the 15th September and has been a huge success with our customers, in no small part due to Apiary.
Long story short: we’ve since recommended Apiary to several other teams at Microsoft and look forward to continuing our partnership as we strive to give developers the thoughtfully designed APIs and documentation that they deserve.