Expanding An API Designers Horizon Using Apiary

I spent some time developing a hello world product API with Blueprint, RAML And Swagger this last week, and along the way I had several experiences that I think are influential in the API design process. One of these was while I was designing my product API using Apiary.io.

After I had gotten to a certain point in my design, and I wanted to see it in action, so I clicked on the preview button. A panel slid out showing me the interactive documentation my developers will see when it is published, and potentially see how it will work with sample API responses, and code samples in a variety of programming languages.

Just like interactive API documentation has been important in teaching developers about an API interface, it will also assist API providers in understanding their own interface throughout the design process, and be able to better articulate the interface to developers.

Another important thing I saw exposed in the Apiary preview pane was code samples for making calls against my product API in PHP, Python, Ruby, C#, Visual Basic, JavaScript, and Node.js. I think this option, built into the API design process is a pretty significant part of the lifecycle, by providing API designers with a constant reminder that their API interface will be consumed in a variety of languages.

A common mistake I see from API deployments is that developers see the world through the lens of their preferred programming language. I’ve seen very PHP centric design patterns, ones that cater to .NET and even APIs that consider only Node.js in their interface design patterns. It is not just the fact that they are thinking only in their programming language that is a problem, its just the fact that they aren't willing see the world through the eyes of their potential developers.

Anything we can do to expand the horizons of API developers during the API design process, helping them see the wider world they are entering into by exposing their API, is a good thing.