In February, InfoQ covered the active community debate around API languages and specifications. About a month after the article was published, the debate took a new and more active turn when SmartBear announced that they were assuming responsibility for Swagger, one of the leading API languages. Soon after the announcement, InfoQ interviewed the founder of Swagger, who confirmed his commitment to keep the Swagger project open.
Recently, InfoQ had the opportunity to interview Uri Sarid, creator of another famous API language, the RAML project. Uri is also CTO of MuleSoft and we appreciate that he was generous with his time to help the community understand RAML’s technology and governance, share his view of the SmartBear acquisition of Swagger, and provide interesting comparison points between RAML, Swagger and API Blueprint.
InfoQ: Can you explain the purpose of RAML and your role in this project?
Uri Sarid: The purpose of RAML is to have a common language for talking about the API itself, a great way to capture the actual contract between the provider and the consumer, and to do it in such a way that it’s as easy as possible to write as well as to read, for both humans and machines, and that you get a ton of value out of it.
My role is that I had the original idea. We looked around to see if there is something out there available. Swagger was one option that we recognized but it wasn’t a good fit, at least at the stage it was at then. We pulled in some people from MuleSoft as well as people outside of the company. I'm still leading it today.
InfoQ: Can you describe in more detail the main parts of the RAML project, beside the language specification, and how they relate to each other?
Uri: So the language specification is at the center, but without tooling it is sterile. There are the various tools provided by many contributors; MuleSoft certainly has some, but so do other vendors such as SmartBear, Oracle, Akana, Restlet. Numerous independent developers have contributed as well on GitHub. There is a very active community of users as well, from independent developers to large enterprises.
InfoQ: RAML version 1.0 was announced in October 2014, almost a year after the release of the first public version 0.8. Could you describe the main changes and plans for a release schedule?
Uri: The main changes are not structural. We corrected some things that were mistakes. For example we fixed the fact that only one example could be provided per resource/method/media type. Then, there are ease of use things like the ability to specify JSON schema in YAML, or the ability to extend RAML to capture more metadata.
Version 1.0 should be out quite soon, as we had a lot of feedback since October 2014. We have started to implement the parser and I would expect that 1.0 will be finalized in a matter of weeks. You’ll see, though, that this 1.0 version of RAML won’t come out as just a spec; we are going to come out with something that is programmatically correct - by which we mean it’s known to be self-consistent, it’s defined formally, and it’s particularly easy to create tooling for.
InfoQ: What is your reaction to the sponsorship for Swagger passing from Reverb to SmartBear?
Uri: I find it extremely exciting. Tony Tam has been a huge pioneer in the API world, but I too have felt that Swagger had outgrown Reverb. Swagger and Swagger UI were initially mixed together, and in people’s minds the API specification itself was not at the center. There was not a strong notion of an API contract itself, which is something RAML focuses on -- that’s why we chose YAML as the underlying format, and why we put out an API designer from day 1. The Swagger contract was more like an intermediate step to the UI, but it has evolved over time: as a sign of the benefits you get from constructive competition, they recently added the YAML format and an API designer to make it more appealing as an API contract spec. We are looking forward to SmartBear’s stewardship, as an experienced and innovative tools vendor, and to continuing to work closely with them.
InfoQ: There are discussions in the Swagger community about the best open governance model for the project. Can you tell us more about the RAML governance model, its organization, level of openness and effectiveness?
Uri: You know, when we looked at the API space and API management space we first wanted to make sure that RAML was valuable: you first have to have something worth governing. We had principles in mind but wanted to see which usage, adoption and value people got out of this. What we are seeing now is an incredible amount of value, beyond what we had expected.
As a result we do need to think about what is the proper governance model for it. I don't want a big commitee that is too formal and heavy. If we become WSDL, we have failed. How do you achieve continuous progress and value is open for discussion. Regarding openness, 100%: the project itself is opensource and we are handling all discussions with the community in a public and transparent manner.
If SmartBear has some interesting model of governance, looking at Swagger 2.0 progress, it’s interesting to see how we can learn from that, and also brainstorm with Ole Lensmar (CTO of SmartBear).
In the end, it’s more about making sure that you create significant value and then use governance to protect that value. Governance itself doesn't create that value.
InfoQ: RAML introduced the notion of traits and types to describe cross-cutting API aspects such as query parameters for pagination on collection resources. Swagger 2.0 has a concept of references at both the JSON and YAML levels. Can you tell us how they compare?
Uri: I think they are quite different. RAML has Includes and Pointers as well, for simple referencing. The fundamental difference is not whether the piece of spec is local or remote, it’s about which structures you want to reuse and make consistent: which patterns are useful and should be encouraged.
A Trait is a behavioral aspect, and traits can be composed (mixed in). A Type is a kind of object or class, and types can have inheritance. I think that it is an important concept for the API ecosystem to come up with reusable patterns for resource types and API behaviors, so that we foster the emergence of more consistency within and among APIs, and that in turn will lead to easier consumption of APIs and an acceleration of the API ecosystem.
To make a parallel with common programming notions: Swagger references (and RAML includes) are equivalent to imports: They allow you to split your code into several files. Resource Types and traits, however, are comparable to Classes and provide a higher level modeling construct.
InfoQ: What are the main strengths of RAML compared to Swagger v2 and API Blueprint v1?
Uri: I think one of them is having Traits and Types. The other difference is that RAML syntax is a lot cleaner. I don't see the structure of the API come out as clearly with Swagger and API Blueprint. With RAML I see the API structure. There is a level of clarity that is qualitatively different between them.
I do think that we are a bit closer to Swagger 2 than to API Blueprint which is focused more towards documentation.
One last comment about documentation. For me that's an artifact produced out of the specifications. In general you don't want to start with the documentation, it’s better to start with the specification, and out of that you produce the documentation.
InfoQ: Do you think one of these API languages will eventually win or is there room for several related languages? What are the chances of RAML to become a de facto standard for API definitions?
Uri: I don't have a crystal ball but we are very actively advancing RAML, with other people on the working group. It’s important to be vendor neutral, and recognize that vendors have their interest which could be aligned with the project or not. With Swagger being owned by a vendor like SmartBear, I believe that it will be in the best interests of the API community. Similarly, MuleSoft’s interests are aligned with RAML not being MuleSoft specific. I think that's the case for SmartBear too so I think Swagger is in good hands.
Merging could happen, like the SOAP world has a single WSDL, but look at the monster we got in the end. Perhaps if it becomes one API language winning it could become a monster. I think we caused Swagger to launch version 2.0. I think it's a great thing, we helped make Swagger better, and we are challenging each other to the benefit of the community.
We are also on the same page with Jakub Nesetril (the creator of API Blueprint). We compete and both are getting better in the end. The growth of RAML has been pretty good, so we'll see.
InfoQ: What are the most interesting community projects that you have seen emerge around RAML?
Uri: I think for me the interesting aspect is the breadth and variety of the projects. There are static code generators, client generators and server generators, converters to and from all sorts of other formats, parsers and other tools in multiple languages and frameworks (some of which I’d never heard of before), testing frameworks, browser and editor extensions and increasingly we see tools built on other tools, for example combining the API designer with the Node.js framework to end up with a mocking service.
InfoQ: What does RAML have to offer in terms of client SDK generation?
Uri: Today there is already an automated client generator framework that does this through templating, so it has central logic for the RAML definition and for activating language- and framework-specific templates with that definition to generate clients for those languages and frameworks. It's up to all of us in the community to write those templates. There is already one for JavaScript and Node.js and another for Python and there will be a few more coming soon as I know people working on those. Independently, there is a .NET client generator integrated inside Visual Studio, and there is a client (and server) generator for Java as part of the RAML-for-JAX-RS open source project.
InfoQ: What is your view on the usefulness of hypermedia APIs? Is RAML supporting this style of APIs or planning to do so?
Uri: In my mind, the jury is still out. I've seen APIs that have done that nicely, but they’re still uncommon. I've had endless interesting discussions with leaders in that world and we concluded that our discussions are not over.
Hypermedia APIs pose severe challenges for the enterprise to write clients for them. But hypermedia APIs are also very intriguing as a way to make APIs durable, which is one of the most important challenges in the API world. The reason for that is simple. If you depend on several hundred APIs (which is not uncommon) and you have each API changing significantly only once a year, you end up with a potentially breaking dependency change every day, so I do see this as important to tackle.
There isn't anything special in RAML today to support hypermedia or to prevent its use. There have been suggestions to integrate hypermedia affordances into RAML but we haven't found a way to do so in a format agnostic way. But I know it is doable to capture those things in RAML, as some people already do it today.
InfoQ: What are the main development workflows that you observed based on RAML?
Uri: One is obviously the API design-first workflow. That's proving very effective, and once you adopt that approach you don’t ever want to go back. People who do that may keep existing APIs code-first initially, but with a move to API-first after.
The other is for people who already have APIs and don’t adopt a design-first approach, but rather use annotations or capture manually the design in RAML and leverage the toolchain. They will still capture use cases to call that API, using API notebooks.
InfoQ: Do you see an evolution from API code-first towards API definition-first workflows?
Uri: We see it inside of companies. It’s been very natural for them to have code and add annotations later. But as they start to see the API as a first class citizen, they start using the API Designer in order to define the next version of the API.
We see that happen a lot, but sometimes also it’s hard for existing developers, so the change happens incrementally. When they want to do a new project, then they start with the API definition first.
InfoQ: Do you have any other thought to share about RAML’s future?
Uri: With one year of public use, it's an extremely important time for RAML. It has had a lot of impact so far but most of the potential is still in the future. The theme people will see with RAML (and maybe Swagger too) is leaning into the advantages of a written, intentionally-designed API specification.
Can we do higher level constructions? Will that make API design even easier and more powerful? Will it open it up to more participants? With Restlet Studio there’s a way to make it even easier to design APIs today. We can generate even more things automatically and that’s the direction where RAML is headed.
If you can create a value chain where you generate tremendous value for developers with as little work as possible, that will become addictive. Look for a lot more of that in RAML coming soon!
If you have an opinion about RAML, Swagger or changes to the API industry, please write your comments below.
Disclaimer: the author of this article works for Restlet, a web API platform provider supporting several web API languages including Swagger and RAML