{"API Evangelist"}

The Vision Behind Swagger, API Blueprint and RAML

Swagger is now Open API Definition Format (OADF) -- READ MORE

I am working through some deeper research into the world of API design, and specifically into the world of API definitions. This research involves talking to each of the leading providers, crafting a series of stories along the way, resulting in a white paper that provides an overview of the space and possibly where things are going.

During my conversations with Tony Tam (@fehguy) of Wordnik, creator of Swagger, Jakub Nesetril (@jakubnesetril) and Z (@zdne) of Apiary, creators of API Blueprint, and Uri Sarid (@usarid) of Mulesoft, creators of RAML, I asked a simple question:

What is the vision behind your API definition format?

Resulting in a little insight behind each approach:

These are my summarizations of what Tony, Jakub, Z and Uri said in response to my question, not direct quotes. I think they get at the essence of why each company has invested so much in defining an API definition that delivers on their separate visions, and meets their goals

I also think there is a lot of overlap in these visions, as well as being in sync with where the overall demand in the API space is going. I don't endorse one solution over the other—I think each API designer will choose, and the fact there are multiple approaches is a good thing.

API definitions play a central role in my API design process, but in my personal approach, theAPI server and client code is regularly thrown away, where my API designs remain constant—something I work to iterate on, much like my writing.

Even with my personal passion for API definitions, I don't think they will be for everyone. I think API designers who find they deliver value in their work will use, while many successful API designers will have no use for them, and be just fine without them.

For some in 2014 API design will be about sharing, collaborating and communicating, in which API definitions will play a central role. For others the API implementation will be where the sharing, collaborating, communicating and ultimately the rubber meets the road.

Updated November 27, 2015: Links were updated as part of switch from Swagger to OADF (READ MORE)