A MuleSoft Concession? RAML Creators Join OpenAPI Initiative to Unify API Descriptions
The Open API Initiative (OAI) added a new member on April 20. MuleSoft, the chief concern behind the RESTful API Modeling Language (RAML), is now a part of the OAI and will be contributing to the OpenAPI Specification (OAS). For the past four years, MuleSoft, an API management and application networking company, has developed and supported a different approach to API documentation and descriptions. Joining the OAI is a path to bringing MuleSoft’s approach and methods into the OAI development committee.
Uri Sarid, co-creator of the RAML specification and CTO of MuleSoft, said that he’s already been speaking about technical details with the OAS committee and that he expects the collaboration to be fruitful. He said that their discussions thus far were able to focus on things RAML supports, but OAS 3.0 does not, and thus, Sarid said some of the decisions made in RAML may influence the future of the OAI.
“The bigger missions for all of us is to get people to lean into API specifications as contracts in a connected API-driven landscape, and we’re all fighting this battle together. The OpenAPI specification is a broadly adopted mechanism to describe APIs. We support that specification ourselves, and we encourage others to support it. It’s the lingua franca. We use this vocabulary and syntax for describing an API specification that will work for everyone. It may not do everything, but at least you’ll be able to understand that,” said Sarid.
He said that joining the OAI, “Signals, in an overt way, that it isn’t about taking sides between RAML as an API modeling language, and OAS as an API description language. We should look at and see the benefits from both sides,” said Sarid. “RAML is designed to help you model your API, design it, and to allow you to have explicitly reusable components. It fosters consistency, so these APIs act similarly.”
https://www.youtube.com/watch?v=5o_nExedezw
On the outside, MuleSoft’s joining the OAI could be seen as a concession that RAML has lost an imagined API specification war. Sarid, however, feels that any such characterization does a disservice to the technical goals behind each project.
RAML was designed to model APIs, and to provide what Sarid refers to as a meta-metadata layer through types and annotations. These higher level constructs allow enterprise users to treat fistfuls of APIs more sustainably, with better descriptions of what exactly each API does.
The OpenAPI Specification, however, describes APIs and automates the generation of documentation around them. This enables developers to move faster, rather than constantly having to go back and update their specifications and documentation every time their API changes.
The OpenAPI Specifications originated as the Swagger 3.0 specification, but in 2015, the OAI was formed under the Linux Foundation. The actual technical management of the specification for Swagger was then taken over and renamed to the OpenAPI Specification. The Swagger name now resides with the set of tools overseen by Swagger creator Tony Tam.
On top of all of that, said Sarid, RAML can still coexist. The RAML community has even produced a set of tools for moving back and forth between OAS and RAML. “By us being part of both sides and creating open source tooling to bridge these two worlds literally brings the best of both worlds to everyone,” said Sarid.
The best of the RAML world is rooted in enterprise use cases, he added. RAML was built to bring reusability and consistency to enterprise API implementations. Similarly to Swagger, RAML arose in an era of RESTful API proliferation. Enterprises were just beginning to understand what it meant to host oodles of microservices in 2013, and as a result, the RAML specification was born to help the understand just what they were building.
In September of 2016, the RAML specification hit version 1.0. The update added annotations, data types, and improved examples. The method by which RAML implements multiple examples, said Sarid, was of interest to the OAI team when they were collectively discussing how such behavior should be implemented in the OAS. Hopefully, said Sarid, this is an example of how the OAI team can work with the RAML team.
The actual benefits of RAML 1.0 are definitely focused on the needs of the enterprise. The addition of data-typing allows that meta-metadata to be accrued around an API data source, ensuring it can be properly plugged into a receiving application without confusion.
Another powerful addition is the annotations. Sarid said that users are beginning to see, “The power of having typed annotations on top of the specification: overlaying the specification. The overlays allow you to annotate the specification, without changing the specification. We now have libraries of annotations,” said Sarid.
He spoke of one developer who has created libraries of user interface controls driven by annotations. “He’s taken standard API specification for a thermal sensor. The Open Connectivity Foundation has published standard RAML specifications for IoT devices. One of those is a temperature sensor, which can be read and set,” said Sarid.
Using that common RAML specification, Sarid said this developer was able to create a library of UI components which tied directly to the sensor. “With that library, you can take that thermal sensor and create a user interface that’s automatically synced up with that specification. A user can then interact with that UI and measure or change temperature,” said Sarid.
And this is the reason Sarid said that RAML is able to help enterprises in ways the standard OAS cannot. In a world where microservices are proliferating, and registries are becoming the center of the application network, Sarid said that RAML can help make life easier for developers struggling to consume all of those disparate services.
“I think it’s a piece of the solution and an important piece. It doesn’t solve it completely, and ultimately you need significant smart software to handle a whole ecosystem of services. A part of that puzzle is to capture that API specification. So far, we’ve all captured that specification as documents. It’s very natural to look at a contract as something you should put in source control. It’s very natural to be document-oriented,” said Sarid.
“However, an API specification actually encodes an object tree, and a graph of business objects it exposes. It’s saying here’s the invoice, here’s the business group that used it, and so on. That object tree, and the relations between those trees, and the operations you can do on that forms an in-memory structure. Where the industry will want to go, and where we’re going in Anypoint, is to really capture, build, and hold business logic around the structure of those APIs. It’s inside the API,” said Sarid.
“API modeling captures all those objects in the API specifications. It’s a piece of the puzzle. It doesn’t give you the registry and software to store all those models and graphs, but builds values on top of those,” said Sarid.
This also allows things like testing and troubleshooting to be properly handled within the specification, said Sarid. “The API specification gives you a bunch of info about the functional aspects of the API. Invoke this method, get this response. But there are more layers of metadata that are relevant. How do I actually test this API? If I do an example, do I get an example back? There has to be extra semantic information you overlay on top to help you test it. There are other areas where you might want to lay down extra info. RAML has reusable components and two-way tripping between them. Your object representation should remember. If you can remember pointers to higher level code, a stack trace can be made meaningful again,” said Sarid.
For now, RAML is not going anywhere. While MuleSoft will participate actively in the OAI, Sarid said that supporting a specific initiative or framework isn’t as important as spreading the gospel of proper, standardized API description. When APIs all behave similarly, all developers win on time savings.
Feature Image via Pixabay.
