Yesterday, MuleSoft, the creators of RAML, announced that they have joined the Open API Initiative. Created by SmartBear Software and based on the wildly popular Swagger Specification, the OpenAPI Initiative is a Linux Foundation project with over 20 members, including Adobe, IBM, Google, Microsoft, and Salesforce.
It should be obvious to followers of the API industry that this is a clear signal of convergence on the OpenAPI Specification (OAS). RAML will continue to provide additional modeling functionality on top of the OAS, but ultimately the contract will most likely be via OAS. Apiary — who is now part of Oracle — joined the Open API Initiative in 2016, bringing the OAS to back their documentation-focused Blueprint format.
How did Swagger (OAS) become the standard?
In looking back, the burning question is, how did the OAS (via Swagger) — with light-weight, community roots — emerge as the leading format from the “Great API Description Wars” between 2013 and 2015? (And all this without formal corporate backing until Swagger moved to SmartBear in early 2015?)
There's marketing, tooling, the (admittedly fantastic) name, etc. But if I step back and ignore all of these factors (which is not easy) and focus on the specification alone, there is a clear reason why Swagger won the war, and the others converged upon it.
Swagger was started with a small number of goals — and covering every use case was certainly not one of them. With that, the founding fathers of Swagger built the project with three simple goals:
- To be human readable. That means the spec had to be concise, organized, and clear enough that a "normal" person could understand it.
- To be machine readable. This required structure and "rules" such that the specification itself could be interpreted to "do something useful" by a computer.
- To be thorough enough to describe everything needed to consume or produce a REST API.
While the initial 1.0 Swagger Specification had it’s share of shortcomings, it certainly followed the rules above, and thus we were able to build very robust and valuable tools to leverage it.
How does this differ from the other two leading formats at the time?
Simple:
- API Blueprint is a very clean documentation format. It's meant for humans and is confined to markdown. Tooling was later developed to allow authoring in different formats, but this was clearly focused on documentation rather than description. What's the difference? It's like reading the abstract of a legal document vs. the document itself. While popular for documentation, the notion of machine-readable structure, strict schemas, and "actionable extensions" simply do not seem to work well with markdown.
- The "ML" in RAML stands for "modeling language". This means RAML has as its design goal the ability to model large numbers of APIs, but this may or may not be what any specific API or developer needs. What they do all need is an agreed-upon way to describe the contract in an unambiguous machine-readable way.
What does this mean moving forward?
Lots! But like the great browser wars in the late 1990's, I believe we're seeing a convergence on a single dialect of description for APIs. This is a good thing (some of us can remember the "this site only works in Netscape Navigator" message) as in the end, consumers of APIs typically don't care how they're described. If the mechanism is standardized, and more "things" can communicate, then everyone wins.
It is satisfying to see the industry rally around the OAS, and now that RAML API specs can be expressed as OAS contracts, we can get the full value from these contracts across the API ecosystem, providing a consensus for machine-to-machine communications and, importantly, to drive the API lifecycle.
We’ve had many public arguments and thousands of personal hours have gone into the project; setting the right goals at the beginning turned out to be the key to winning the hearts of the REST community, and as such we look forward to working with MuleSoft’s RAML team to leverage their domain expertise within ongoing OAS efforts.
[caption id="attachment_694" align="aligncenter" width="310"]
One of the many IPA-fueled public debates during the great API Format Wars of 2013 with RAML creator Uri Sarid, API Blueprint creator Jacob Nestril, and Swagger creator Tony Tam[/caption]
UPDATED: This post was updated to clarify some factual points and address some potential misunderstandings.