Is it possible to have your cake and eat it too? In the world of API specs, we believe the answer is yes. We have been strong supporters of RAML, the RESTful API Modeling Language, since its inception, and we are if anything even more excited and committed about the value it brings to the API ecosystem.
Last week, we also joined the Open API Initiative of the Linux Foundation, and I’ve started to participate in the Technical Developer Community for its API spec format, OpenAPI Specification (OAS). While RAML has emerged as the leading way to model API specifications, OAS (formerly Swagger) has emerged as the most common format for describing APIs. Although they share many aspects in common, they have different design goals, so developers and companies have been wondering: which should I choose? The answer is: both!
We wanted developers to have the best of both worlds, so we developed and open sourced the API Modeling Framework; this is software that layers RAML modeling atop OAS description, enabling interoperability and providing common programmatic capabilities to any API spec. But software is not enough to truly facilitate collaboration, so we have also joined the Open API initiative because we believe that working together will improve both RAML and OAS and afford value to the entire ecosystem.
Our commitment to API-first strategy
As a company, we have been in the API space for many years. Our journey into API specifications began in 2013, when we, along with a workgroup of like-minded individuals and companies, created RAML, the RESTful API Modeling language. At that time, most developers creating or consuming RESTful APIs relied either on manually generated documentation, or on documentation generated from code annotations via popular toolsets like JAX-RS and Swagger. Such intermediate formats included the Swagger spec, IODocs, WADL, and others. We felt it was important to focus attention on the API specification itself as a top-level concern, a formal, machine-readable and verifiable contract between the producers and consumers of services, and not just an intermediate generated artifact between the implementation code and the human documentation of the API.
Even further, we advocated that developers, product managers, and architects treat APIs as products, to be designed and modeled up front and explicitly, and we put our money where our mouth was. When we launched RAML with the RAML Workgroup as an open, vendor-neutral specification, we also simultaneously open sourced the tools to support this approach: an API Designer for modeling APIs, an API console to immediately show the API documentation as the API was designed, a mocking service to simulate it as it was designed, a try-it capability built right into the console, and an API Notebook to script API consumption scenarios using API clients automatically generated from API specifications. RAML’s design goals supported this approach explicitly: while it provided a strong contract, it was optimized for humans to read and write, and it had built-in modularity and support for patterns that could be refactored out and reused to foster consistency. Adoption of this approach and of RAML took off and has been growing ever since. Most importantly, developers and enterprises saw the benefits of this API-spec-centric approach and, the industry has since incorporated it broadly as a best practice.
The API spec ecosystem
Naturally, we were not alone in this space; Apiary’s Blueprint format and tooling also emphasized the API specification and the contract- and design-first approach as central, and soon after, with the launch of the Swagger editor, the Swagger ecosystem did as well. In this post, rather than discussing which specification or group was responsible for which advancement, I actually want to acknowledge the value that the co-opetition between the various API specification technologies has brought to the API community as a whole. There is not only broad recognition of the importance— indeed, the centrality — of a tight API specification; there is also a rich selection of tooling for API producers and consumers, a growing set of service providers that officially publish API specifications and who have committed to adhering to them, and increasing adoption of API-first principles by developers, whether within organizations, with thousands of developers, or in the long tail of smaller companies and individuals.
And what about API specification formats? Two approaches have emerged, each with a different design goal. Swagger is now reserved as the name for SmartBear’s specific API framework software, while the specification itself — now known as the OpenAPI Specification (OAS) — has been contributed to the new Open API Initiative in the Linux Foundation. OAS version 3.0 is now being finalized, and will hopefully gain broad adoption as the common way to describe API specifications; its design goal is simply to be a universal common format for describing RESTful APIs. RAML, on the other hand, has API modeling as its design goal: it cares explicitly about making it easy and efficient for developers (humans!) to model APIs, to express the models succinctly and in terms of reusable patterns and components, to foster consistency across APIs, and to separate the concerns of API functionality, API security, API testing, and so on. Both approaches are humanly-readable and -writable, both serve as strong contracts between consumers and producers, and frankly both have grown quite similar to each other — because both are developed in the open, serving communities with many similar concerns.
But inevitably, the part of the API world that cared about API specifications — happily, a growing percentage — saw a “war” ensue between these API specification formats, and felt a need to choose between one and the other. We believe it’s time to “bury the hatchet” and to find a way to offer the best of both approaches to the API community.
How to have your cake and eat it too
To that end, we believe everyone should support a common format that can at least describe the service model of an API — that is, what an HTTP request to the API should look like, and what the responses should look like. And we believe that format should be the one most commonly-adopted today: the OpenAPI Specification. That is one important reason for MuleSoft joining the Open API Initiative, and for MuleSoft’s Anypoint Platform explicitly supporting OAS for describing APIs. It should be our lingua franca.
And also to that end, we believe strongly in the value of modeling APIs, of enabling developers to express both the common and the unique aspects of their API products in a clean, clear format, one that clearly separates the various concerns of an API contract, one that is explicitly modular, a format that is ideally suited to be the “source code” of their API: RAML. That is why we are, and will continue to be, committed to supporting the RAML initiative and investing in and broadening its ecosystem. If you are an API professional and treat your API specification as your product specification and contract with your customers, if you are deeply invested in an API-first approach, if you are building an ecosystem of APIs and are intentional in driving for consistency and best practices and a fully-developed API lifecycle, this approach is calling your name.
The API Modeling Framework – bridging the two worlds
To explicitly bridge these two approaches, MuleSoft has built an open source API Modeling Framework (AMF), available now under the Apache License, which reads and writes both RAML and OAS. In so doing, we are explicitly committing to interoperability between RAML as a modeling language and OAS as a description language. As a developer, you can design and model your API in either format, but RAML offers many more capabilities for modeling, succinctness (the “DRY” principle), reusability, consistency, modularity, and separation of concerns — that is its design goal, after all. Developers can describe their API in either format, but OAS enjoys broader adoption across a wider spectrum of tools and vendors. With AMF, you can choose either format depending on which design goals are important for you, and benefit from a common document model (DOM), a common service model, and a common domain model for programmatically interacting with the API specification in either format. We’re just beginning the journey of exploration into the power of these document, service, and domain models for APIs. To kickstart this, we’ve created a demonstration playground on GitHub — we invite you to join us and, together, to discover what power and capabilities they will bring.
We also want to recognize that while a lot of innovation has taken place through the competition between the two specifications, it’s high time the entire community explicitly works together to share common ideas, unify where the design goals overlap, and acknowledge the value of each approach where design goals diverge. To that end, I and some of the other RAML contributors have also joined the Open API Technical Developer Community discussions. We are truly committed, in good faith, to contributing to the evolution and broad adoption of the Open API Specification, and to supporting the Open API community and building bridges across the entire API ecosystem. We all believe that, through this cooperation across the entire API community, as we innovate and solve problems and focus on adding value while staying transparent, everyone benefits.
