RAML and API Blueprint: where are they now?

The API design battles have long been settled. But occasionally, someone asks, “Should I use RAML, or should I use OpenAPI?” If your team doesn’t use MuleSoft’s Gateway, you may never have heard of RAML. Similarly, if your team doesn’t use Apiary in Oracle, you may not be familiar with API Blueprint. This article revisits the API design skirmishes that started over a decade ago and explores where those formats are now.

The API design battles

In the API design war of the early 2010s, specification formats battled it out for industry domination. When the dust settled, three formats emerged as promising contenders: API Blueprint, RAML, and Swagger (later renamed OpenAPI).

• API Blueprint is a markdown format to generate documentation. It was developed by Apiary in 2013 and then acquired by Oracle.
• RAML, which stands for RESTful API Modeling Language, is an API design format that was developed by MuleSoft in 2013 and then acquired by Salesforce.
• Swagger is an API description format that was developed by Wordnik in 2010 and then acquired by SmartBear. It was later renamed OpenAPI and donated to the Linux Foundation.

OpenAPI won the war

In 2015, a few notable companies joined together to form the OpenAPI Initiative of the Linux Foundation to develop a universal standard for API specifications. Standardizing the way APIs are designed and documented makes them easier to maintain, adopt, and use.

Apiary eventually joined the initiative in 2016, with MuleSoft following suit in 2017. Today, both companies support OpenAPI, in addition to their own formats. These symbolic gestures signaled to the rest of the specification community a willingness to collaborate for the benefit of the overall API ecosystem. This cooperation extended across teams and companies with the goal of a consistent and predictable way of designing APIs.

In 2023, when people talk about a design-led approach to API-first, OpenAPI is the most widely used specification format by a large margin. In Postman’s State of the API report, OpenAPI 2.0 (a.k.a. Swagger 2.0) and OpenAPI 3.x were the most widely adopted API specifications, with 39% to 55% of respondents using each version. This is in comparison to RAML and API Blueprint, which both have 7% adoption.

Why did OpenAPI win the war?

OpenAPI (then named Swagger) was first to market, but there were some other key factors that helped adoption spread rapidly through word of mouth:

• Open source ecosystem: Swagger, RAML, and API Blueprint were all open source projects. However, Swagger touted a rich ecosystem of open source tools, code generation, and client SDKs, empowering the community to grow more organically. The API community could still support Swagger by contributing to the open source software surrounding the standard, even if they didn’t directly contribute to the open source standard itself. By comparison, tooling providers were competitors of the RAML and API Blueprint format providers, which made them hesitant to support their competitors’ formats.
• Tooling agnostic: Swagger was incubated at an API company, Wordnik, and the standard was tooling agnostic as a result. By comparison, RAML and API Blueprint were developed by API tools, which meant that early users of RAML and API Blueprint needed to consider future vendor lock-in.

Is OpenAPI a better format?

There is certainly no dispute that OpenAPI is the most widely used standard. However, RAML and API Blueprint both address legitimate issues, oftentimes in a more targeted manner.

For example, consider the differences between OAS and RAML. In 2017, MuleSoft said, “RAML has emerged as the leading way to model API specifications, [OpenAPI] has emerged as the most common format for describing APIs.”

There are similarities and ambiguity when using those terms. If we ask ChatGPT to tell us the difference between “modeling” and “describing” an API, it tells us, “API modeling refers to the process of designing and defining the structure of an API, including its endpoints, request/response formats, and error handling. It involves creating a blueprint of the API’s functionality and behavior. API describing, on the other hand, refers to the act of documenting the API, including its purpose, usage, and reference information such as available endpoints, request/response formats, authentication methods, and error codes. The aim of API describing is to provide developers with all the information they need to effectively use the API.”

In other words, RAML was developed to model and design an API, while Swagger was developed to describe and document an API. You might expect API producers to favor RAML at the beginning of the API lifecycle, when they are deciding what an API should be. API producers might then generate a Swagger file once the design has been finalized to enhance the developer experience for API consumers. Regardless of the intention, both formats can be used for either modeling or describing APIs throughout the API lifecycle.

In fact, with such widespread adoption of OpenAPI, API producers now use the format to both design and document their APIs, and we see several implementations of API-first. API consumers are also vastly more familiar with OpenAPI compared to the alternatives. For these reasons, debating the merits of each standard is moot, since OpenAPI has already won the war.

If you are a MuleSoft developer, you can still choose to use RAML and OpenAPI. If you are an Apiary developer, you can also choose to use API Blueprint and OpenAPI. However, OpenAPI has substantially more adoption, a richer ecosystem, and more community support. As the most popular API platform in the world, Postman also supports OpenAPI and RAML.

The OpenAPI Initiative wants you

The OpenAPI Initiative is open for a reason. It’s driven by a coalition of appointed members across industry, but they hold open meetings every week and welcome community proposals and commentary. Pundits are vocal in their debate about what functionality is still needed and where OpenAPI should go next. For example, Erik Wilde wrote about the future of OpenAPI, and the API Handyman discussed the next version of the format.

If you want to get involved with the future of OpenAPI, sign up for notifications for their weekly discussions on Zoom or join their Slack workspace.

As developers, there are multiple options to choose from and there is freedom to customize your own solutions. Just don’t develop your own custom standard that works only with custom tooling and proprietary libraries, lest you kick off another API specification war. Let us know in the comments below which API format you prefer and why.

Technical review by Kevin Swiber