The state of RAML?


#1

Hi, am looking into the best way to spec out, document, built and test an API these days.

It seems that these days the general idea is to use RAML for designing, then convert to OAS for documentation/implementation/testing, given the communication around the people behind RAML joining the OAS initiative last year, correct?

I realy like RAML for designing, as the API we’re designing has a lot of similarities between endpoints for which RAML seems to be the best fit to keep things DRY.

However, RAML 1.0 was releases in April 2017, I cannot find any reference to a version 1.x or 2.0 (no new branch in the GitHub repo for example) and I’ve concluded that there is a mismatch to what RAML 1.0 offers and what OAS 2.0 offers.

For example:

OAS 2.0 has properties like readOnly and writeOnly, which are tied to the HTTP Methods and allow you to have a single type definition for the payload/body of get/put/post’s, while differentiating the differences in payload between those HTTP Methods, thus sticking to the DRY principle. RAML doesn’t support those properties natively. You can use Annotations for just put it into your RAML documents, but none of the existing convertors will act upon those annoations. There seems to have been some effort in trying to make annotations more usefull to this respect, but that initiative seems pretty dead as well: https://github.com/raml-org/raml-annotations/pull/2. (also see RAML 1.0 data types, required properties and GET, PUT, POST, https://github.com/raml-org/raml-spec/issues/610)

So I’m wondering what the state of RAML is. Is a new version in the works that will align RAML better with OAS? Are there plans to keep keep releases of RAML and OAS in sync, so that RAM can be used icw with the latest version of OAS without loosing/missing out on stuff?

If I complely missed some info about the ongoing efforts on RAML, I’m sorry, please correct me :slight_smile:


#2

I will try to answer each of your points.

It seems that these days the general idea is to use RAML for designing, then convert to OAS for documentation/implementation/testing, given the communication around the people behind RAML joining the OAS initiative last year, correct?

As you said, given the fact that MuleSoft has joined the Open API Initiative and that MuleSoft is a major contributor of RAML, there will be more and more synergies in the future. In fact, when you look at the evolution of OAS 3.0 and things like components or examples, you can tell that it already started happening.

To answer your question, I think it’s a matter of what tooling you use. If you’re planning on relying solely on opensource tools then the approach (“idea”) that you described is the right one. However, if your organization has specific requirements, you might find that those tools are not sufficient and your organization will have to decide whether it wants to rely on commercial services (e.g. AWS, Restlet, MuleSoft) or build its own. In which cases, the format doesn’t really matter.

I realy like RAML for designing, as the API we’re designing has a lot of similarities between endpoints for which RAML seems to be the best fit to keep things DRY.

That’s exactly why people enjoy using RAML, and that’s why I like it too. I think you should use the format that you feel the most comfortable using and that best suits your (organization’s) needs based on what I described above.

So I’m wondering what the state of RAML is. Is a new version in the works that will align RAML better with OAS? Are there plans to keep keep releases of RAML and OAS in sync, so that RAM can be used icw with the latest version of OAS without loosing/missing out on stuff?

If I complely missed some info about the ongoing efforts on RAML, I’m sorry, please correct me :slight_smile:

I can’t really talk about any future release plans at this time but I can tell you that there has been some very interesting efforts around the API Modeling Framework which provides a language-agnostic way (both RAML and OAS are supported) to model, validate, differentiate and query API definitions. You can see some examples here. Stay tuned for more on AMF in the next few weeks.


RE your question on a RAML equivalent for readOnly/writeOnly, I saw that you commented on #610 so I will try to answer it there.


#3

Hi Jonathan,

Tnx for the elaborate response. A couple of responses

I don’t mind using commercial tools, but I do like to stick with open standards (RAML, OAS(3) etc.). I’m not sure if my organization has specific requirements. So far the only thing I came across that feels like just using RAML and OAS is the example I gave, with RAML not supporting readOnly and writeOnly nativaly, only through annotations, but those getting lost when converting my RAML to OAS through the tolling I’ve tried so far.

But you said your respond to that question in #610, so I’m hoping for some guidance there :slight_smile:
Paul


#4

My pleasure.

RE your specific issue, I answered on the PR and also wrote a blog post about it because I think it deserved some clarification. Bottom line is that there is already a way to achieve this in RAML, which by design, makes you write things in a more human-readable way. I hope it answers your question. If you’d like to discuss this further, feel free to create a new thread in this forum or join our Slack.