A Short History of OAI and API Specifications

When developers started around 2003 to look into REST APIs as a lighter alternative to SOAP services, not only were the heavy set of specifications discarded, but the associated tooling  was perceived as unnecessary. REST and pure HTTP being so much simpler and by nature very interoperable, why would you need contracts, code generators and other sorts of tooling?

At the time, code-driven was the main way to implement REST APIs. This method was supported by various REST API frameworks such as Jersey, created by Marc Hadley and Paul Sandoz from Sun Microsystems, or the Restlet Framework that I created even earlier in 2005. But, as REST API projects matured, the need for more tooling started to reappear…

Based on the initial experience of WSDL in the SOAP era, a first attempt at formally describing REST APIs called WADL (Web API Description Language) emerged at Sun from the same Marc Hadley and was submitted to the W3C in 2009. It had many ingredients of its successors but was hindered by its reliance on XML, the lack of development after the acquisition of Sun by Oracle and the departure of its creator Marc Hadley in 2010.

Soon after, Tony Tam started the open source Swagger project at Reverb to provide interactive API documentation and client SDKs generation for his Wordnik APIs. Swagger became well-known for its nice visual API documentation, now called the Swagger UI. It is a webapp that dynamically retrieves the API description by pulling a JSON document from the API server.

Then, developers started to produce this JSON document dynamically, for example by introspecting Java code for JAX-RS API or Restlet Framework API to collect the necessary API contract information. The increasing importance of this informal Swagger JSON document was recognized by Tony Tam and he started his journey to formalize it as the Swagger Specification.

Around 2013, three competing API description languages were emerging, each one of them taking a different starting point and offering complementary perspectives.

  1. Swagger Specification was part of the grassroots Swagger open source project focused on code-driven developer needs without formal corporate backing by API vendors beside significant contributions from Apigee. In addition to its technical qualities, its focus on describing the core API contract (JSON format) was a strength for its ongoing adoption.
  2. API Blueprint ¬†was created by Jakub Nesetril during a hackathon as a more human readable alternative (Markdown format) to WADL and Swagger and was launched by Apiary in 2013 with a focus on consumer-centric API documentation. The specification evolved to cover the full API lifecycle needs and tooling for mocking or testing was added. Despite availability of the whole project in open source, it was difficult for other API vendors to heavily invest in it with such control from a competing API vendor. 
  3. RAML was created in 2013 as well by Uri Sarid from MuleSoft as an alternative to Swagger, focusing on both human and machine readability (YAML format), ¬†with a focus on API design as its name indicates (RESTful API Modelling Language). It was developed to ¬†suit the needs of larger API providers. Despite the availability of RAML as an open source project, the development of a true community and support by other vendors, MuleSoft’s strong presence limited its ability to be embraced as a standard.


Release after release, each initiative improved its specification and the tooling around it, developing their specific vision, taking into account community feedback, differentiating with other specifications and ultimately competing for mind share and traction.

With the announcement of the Swagger 2.0 Working Group in 2014 during the GlueCon conference, significant progress was made to go beyond the grassroots project and to structure the Swagger Specification more formally to accelerate the rate of community adoption. Additional API vendors embraced and embedded Swagger one way or another in their products.

When SmartBear acquired the Swagger project early in 2015 there were serious concerns about the ability of the project to keep its vendor neutrality and continue on its success path but Tony Tam was committed to keep the project open. After several months of intense thinking, SmartBear announced the donation of the Swagger Specification to the Linux Foundation as part of a new Open API Initiative created with several founding members including 3Scale, Apigee, Capital One, Google, IBM, Intuit, Microsoft, Paypal, Restlet and SmartBear. The specification was renamed OpenAPI Specification (OAS), keeping the Swagger project focused on the open source tooling around OAS.

In the OAI, Tony Tam took the lead of the Technical Developer Community¬†(TDC), keeping the grassroots developer spirit alive, while SmartBear’s CTO, Ole Lensmar, became chairman of the Business Governance Board (BGB). With the experience of the Linux Foundation in fostering this type of initiative (especially with the Open Containers Initiative) and the presence of a significant subset of the leading API vendors, the OAI was launched at the end of 2015. In the meantime, both API Blueprint and RAML continued their progress and I had the chance to interview their creators for InfoQ in 2015 to discuss each initiative (see the interview with Uri Sarid, creator of RAML, and the interview with Jakub Nesetril, creator of API Blueprint).

Last year RAML 1.0 was finally released, bringing a significant amount of innovation around the modelling needs of API teams dealing with an increasingly large amount of APIs and facing challenges such as API style consistency, reuse and collaboration. At this point, it became clear that while OAS had taken the lead as the standard core API contract specification, API Blueprint had developed remarkable innovations around other aspects of the API lifecycle such as the API documentation, while RAML had done the same for API modelling.

Instead of keeping direct competition between the three efforts going on, hoping that one would win and replace the two others, a better path became necessary and possible. Being close to the main actors of this story and building tools such as Restlet Studio that support both OAS and RAML and listening to our users, I realized that the ideal would be to have Apiary and MuleSoft join the Open API Initiative and contribute step by step to the convergence, not necessarily the merging, of the three specifications. On the API testing front, there are similar standardization needs, but beside the HAR (HTTP ARchive) format, only proprietary formats are available such as Postman Collections or JMeter Scripts.

On top of the upcoming OAS 3.0 release, I envision a future release of RAML that would extend the OAS specification to capture API modelling information present in RAML 1.0 today and more. It would keep OAS core simple and focused, while enabling better interoperability between API modelling tools and help protect the investment of API teams during design-time. As Restlet is part of both the OAI as a founding member, and the RAML workgroup since last week, I’m looking forward to directly contributing to such efforts.

There is also an opportunity for similar efforts around the API testing and API documentation needs, and I hope that similar convergence efforts around APIs.json, Postman Collections and API Blueprint will happen as well. On the API operations front, I see more and more the needs to define a standard specification that would enable API toolchains to automatically manage APIs in various API gateways and catalogs, reducing the needs to integrate with proprietary APIs.

Putting the API community first, Apiary made the decision to join OAI last year, and I’m thrilled to see the MuleSoft has just made the same decision. In addition, the great API Strategy & Practice conference created by 3Scale and Kin Lane (API Evangelist) has recently been moved under the umbrella of the Linux Foundation and the Open API Initiative, further bringing the whole API industry and community together. At Restlet, we look forward to working with all the OAI members to further industrialize and democratize API technologies.

Join The Conversation


Leave a Reply