RAML or OpenAPI - How About Both?
Struggling to decide which API spec to adopt, RAML or OpenAPI? Mulesoft recently lowered the risk of your choice by making the decision to support both specifications.
Join the DZone community and get the full member experience.Join For Free
For those who remember the debate between VHS and Betamax or Blu-ray and HD DVD, there were vendors on both sides of the technology - banking that their decision would be the chosen standard. Until VHS and Blu-ray were victorious, a great deal of effort was put into the Betamax and HD DVD technology, which was lost when the rival solutions became victorious.
In technology, there have been competing standards over the years. Some may remember the Internet browser wars (Internet Explorer versus Netscape), the whole video streaming competition (Microsoft and RealNetworks), and even the three-way battle for the de facto standard for office productivity (Microsoft, Borland, and Lotus).
Today, I am focusing on the race for an API standard, with the two major specifications being RAML and OpenAPI.
RESTful API Modeling Language (RAML) is a language intended to describe RESTful APIs. The RAML effort was first proposed in 2013 and garnered support from technology leaders like MuleSoft, AngularJS, Intuit, Box, PayPal, Programmable Web and API Web Science, Kin Lane, SOA Software, and Cisco.
The goal of RAML is to provide all the necessary information to describe RESTful APIs, thus providing a simpler way to design APIs.
The OpenAPI specification provides support from Google, IBM, and Microsoft and was built from the Swagger specification, owned by SmartBear software since March 2015. Using the OpenAPI specification within program code, files can automatically be created to document methods, parameters, and even models.
The goal of OpenAPI is to keep documentation, client libraries and source code all in sync.
Which to Pick?
Depending on prior projects, I have been able to utilize both approaches. Honestly, both specifications have a great deal of promise and have the "right" end goal in mind - to provide easy/automatic descriptions and documentation around APIs.
From a functional perspective, Swagger has been a proven solution - providing strong documentation tied directly to the source code, which is a nice feature. RAML seems to be a step ahead - providing the idea to conceptualize and simulate the functionality, which is certainly a benefit in the design phase.
Until recently, Mulesoft was a strong contributor to the RAML effort. In fact, a great deal of their training and media announcements included references to RAML as a benefit to using their preferred specification.
As detailed in the "Open API and RAML: Better Together" blog entry by Uri Sarid, Mulesoft is now adding support for the OpenAPI specification into their API toolset. The addition of the API Modeling Framework (AMF) open-source offering should provide comfort for those using the Mulesoft platform for their API needs.
To compare Mulesoft's approach with similar standards battles, it would be like Mulesoft mass producing both VCR and Betamax devices or Blu-ray and HD DVD devices. Certainly, the effort involved wasn't minimal and the additional tasks involved were not required, but their decision to continue to focus on the greater good of the API specification is evident with their decision.
Which standard do you think will win in the end?
Have a really great day!
Opinions expressed by DZone contributors are their own.