Developing The Language We Need To Communicate Throughout The API Lifecycle28 Jun 2014
Swagger is now Open API Definition Format (OADF) -- READ MORE
We are still in the infancy of the API economy, and now with barely 14 years of evolving web API design, we are only just now developing the languages we will need to communicate around APIs throughout their lifecycle, from the first mock of the API resource, to monitoring of a production API in the wild, or making available to a new breed of API search engines.
There has long been standards for describing APIs, such as WSDL for SOAP, and WADL for web APIs, but these formats would never actually enable the meaningful interactions around APIs that it would take to find widespread adoption. WSDL was too programmatic, and heavy handed, while WADL never possessed the incentives for API providers to take the time to define their APIs using the heavy XML format.
It wasn't until early 2011, we would see the first signs of a meaningful language for defining web APIs, that would enable us to have productive conversations, and take action around our API designs. In February 2011, online word meaning and definition site Wordnik, launched a new API developer portal, complete with a new way to document APIs, that was interactive, and allowed developers to make live API calls, while learning about an API. In an effort to keep their API documentation up to date, Wordnik has also established a new way to not just document and communicate with an API, but allow us to actually have a shared conversation about the actual design of the API itself.
Later on that year, API management provider Mashery emulated Wordnik's approach, and launched their I/O Docs. Immediately after, in August 2011, Wordnik formally launched their approach to defining APIs, generate interactive documentation, and server or client side code—which they called Swagger. Over the next two years the Swagger ecosystem would grow and evolve, producing new versions, tooling, and implementations of both private and public API implementations.
During this time, the concept of API design would expand, with tech giants like Google establishing their own approach, which they called Google Discovery, and we would see a new breed of API design service providers emerge with Apiary.io. By March 2013, Apiary had launched their own API definition format called API Blueprint, which allowed API providers to define an API using markdown, and iterate on the design using Apiary.io services. Apiary moved the incentives for defining APIs in a machine readable format earlier on in the lifecycle. Now we didn't just generate machine readable definitions to deploy server code, or generate interactive docs and client side code, we would do it before we actually deployed the API, allowing us to mock our API designs, and collaborate around designing the actual API prior to deployment.
Then by the end of 2013, we'd see another API definition language emerge, this time from enterprise technology provider Mulesoft, called RAML. This new approach to defining APIs, would use YAML to produce a machine readable, yet human friendly way to describe APIs. Now we had four new ways to describe our APIs, and as we push into 2014, we have a wealth of tooling, services, and a selection of maturing API design editors to choose from when planning and designing our APIs.
I feel like we are just moving from infancy, into the toddler phase of communicating throughout the web API lifecycle. We now have several languages to choose from, we just have to work hard to educate people that they exist, help them become fluent, and expand the incentives for generating machine readable definitions for our APIs. In the next year, I predict we will see an increased adoption of the leading API definition formats, new tooling and services that helps us design, deploy, manage, monetize, evangelize and integrate with APIs that are driving the API, and app economy--driven from a central, machine readable API definition.
Updated November 27, 2015: Links were updated as part of switch from Swagger to OADF (READ MORE)