Gandalf, still not making sense of your docs

The Three Styles of API Documentation

API Documentation comes in a variety of forms. You can find it in pdfs, html, or even a Postman-collection that lets you play immediately. You can provide project examples, detailed blog posts, or video walk throughs.There are tradeoffs of each. Regardless of how you deliver the documentation, all  documentation fall into one of three buckets: […]


The Case for a Great Developer Experience

All opinions and analysis in this post reflect my experience and opinion, not those of current or previous employers. They did not review or approve of this in any form. For years I’ve advised everyone from solo developers to Fortune 50 companies on the best approaches to designing and building APIs in addition to numerous […]


Social APIs for Social Evil

Note: To be clear, I am not accusing AirBnb or Facebook – or anyone else – of allowing this. According to my understanding of their Acceptable Use Policies and the law, this is way out of bounds and likely to result in trouble for all involved. Do not do it. Updated March 2018: I have […]


Every API Company has Three User Interfaces

This was originally published on the Clarify.io blog, reproduced here. When I joined Twilio in early 2011, I learned that API companies have three user interfaces: First, there’s the website. It’s what we all think about because it’s the first thing most users see. We have designers, UX people, and similar who spend a lot of […]


Operation Buy It Now

My first book – “A Practical Approach to API Design” – shipped this past Friday. As a result, I’m activating Operation Buy It Now today. To sweeten the deal, if you order it by 11:59pm  ET on Sunday the 23rd, you will be entered into a random drawing for four hours of API consulting. All […]