RESTful API Modeling Language (RAML) – approach with caution

The RESTful API Modeling Language (RAML) is a relatively new proposed standard that surfaced in late September 2013 and is being heavily promoted by MuleSoft. RAML is described as a concise, expressive language for describing RESTful APIs that faces competition from Blueprint, Swagger, and WADL (to name a few).1

Mulesoft is arguably the biggest proponent of RAML and heavily relies on the standard to specify RESTful services later implemented with their Mule ESB and CloudHub products. The MuleSoft CTO, Uri Sarid is a member of the RAML workgroup and many of the commiters to RAML.org projects are Mulesoft employees.

I am cautious about using RAML as a standard for the following high level reasons discussed in greater detail later in this article.

  • RAML is not a widely adopted standard
  • RAML documentation is not robust.
  • Existing RAML editors need improvement
  • Code generation and round trip development based on RAML is limited
  • RAML is not widely supported in developer tools

Usage of RAML starts with the language specification. This is what developers apply to begin the development process. RAML is a top down, or contract first approach to RESTful endpoint design. This is not necessarily a bad approach, but it does not embrace the community of bottom up, or code first developers. An early release JAXRS-to-RAML file generator is available on raml.org for generating a RAML file from existing JX-RS annotated code. However, the tool is a one way conversion and does not reflect updates made to the RAML file after generation back into Java code. A separate early access RAML to JAX-RS code generator is also available on raml.org but is not well suited for iterative or round trip Java code development. RAML is truly intended for top down development leaving RESTful bottom up Java code developers arguably better served by using tool like Swagger.

The RAML specification is hosted on github and available for download. The specification file itself is formatted using markdown which seems odd. If one of the goals of RAML is to promote usage of the specification, why can’t it be provided in an easy to consume format like PDF? True, you can view the existing specification on-line, or, as a developer, leverage tools to generate HTML from markdown. Neither of those options serves the technologist population simply looking to read and review the RAML specification offline perhaps while traveling and using tablets or other portable devices.

Perhaps reviewing the RAML specification is not your thing and your preference is to look over documentation. Located on the raml.org web site, is a documentation section. Within that section there are two tutorials that can be reviewed. A RAML 100, and a RAML 200 tutorial, with the later containing the more advanced text. The two documents progressively present content of increasing complexity, but together do not cover all facets of the RAML specification. Given the aforementioned are tutorial files, one can look for a reference manual with in-depth explanations, and examples to fill in the holes. But such a RAML reference document does not currently exist. There also are currently no books discussing RAML available. The specification is the definitive, and currently only reference text available. For now, using the forum on raml.org is the hit or miss way to get answers to questions on the RAML specification.

After reviewing the RAML specification and perhaps asking questions about it, the next step is to try and apply it. RAML based files can be created using a standard text editor or by using one of the two editors that MuleSoft offers. MuleSoft AnyPoint Studio has a built in editor, and an on-line editor known as API Designer is also available. Each editor has different functionality and they can’t easily exchange content. To do so, you will need to devise a cut and paste strategy. The on-line API Designer is the most advanced text editor for RAML. While there is a level of intelligence built into API Designer to suggest RAML language constructs as you type, there is no on-line documentation associated with suggestions provided. Users can find themselves entering content, have content suggestions displayed by the editor, and still have no idea what to do next. The ability to gracefully navigate yourself into a development situation where you have no idea how to continue is a consistent criticism I have about MuleSoft tooling. Property sheet editors are not guided wizards, and a lack of on-line documentation and tool tips diminish significant value from syntax suggestions. Developers without in-depth knowledge of the RAML specification will face challenges getting starting.

Still, the MuleSoft RAML editors can get you started using the specification. The tools do have some features like syntax highlighting and limited error checking built in. However, what a developer sees in the editor is raw RAML text. There are no graphical editor options that visually abstract RAML syntax making it easier to enter. In fact, if you want any alternative to the MuleSoft RAML editors, other than a plain text editor, you are currently out of luck. Multiple Google searches run the middle of July 2014 did not reveal other editors available or under development. Why? Certainly improvements and innovations are possible compared to the currently available RAML editors.

  • Is there commercial value associated with RAML tooling?
  • Is there a lack of open source community excitement overall about the future of the specification that would otherwise be a catalyst for tool development?

Different people will have different opinions on the answer to those questions. However, the current marketplace for RAML editors is clearly the exclusive domain of a software vendor that relies on use of the specification to successfully implement key functionality in it’s product line.

How hard would it be to integrate RAML into developer tooling and integration products? Several of the raml.org projects are open source parsers that could be used for such an effort.

  • RAML JavaScript Parser – A reference implementation of a RAML parser for JavaScript
  • RAML Java Parser – A reference implementation of a RAML parser for Java
  • Pyraml-parser – A reference implementation of a RAML parser for Python
  • RAML Ruby – A reference implementation of a RAML parser in Ruby
  • PHP RAML Parser – A reference implementation of a RAML parser in PHP

Only the Javascript and Java parsers are considered stable and appear to be maintained by Mulesoft employees under the Apache 2 license. The Python, Ruby, and PHP parsers are currently labeled early release and being maintained by varying individuals under the MIT license. How are these parsers intended to be used? Is there a desire to have all parsers implement the same functionality? Unfortunately there is no documentation beyond limited read-me files associated with any of the parsers. The code is open source making learning via code inspection possible. However, inspection of the Java code reveals that it contains few comments comments which can slow down learning.

So why are there so many parsers as part of the RAML project? It is not unreasonable to conclude that the answer is to drive up usage of RAML in tools. As mentioned earlier, MuleSoft is by far the largest single promoter of RAML usage. MuleSoft product offerings rely heavily on the standard for implementing RESTful endpoints and is a key enabler of their API product strategy. However, a single company driving a standard for its own best interests will not make a standard a success. In order for RAML to be successful it needs broad community support. Community uptake of the RAML standard, tools, and utilities will be the topic of the next article on RAML.

1“RESTful API Modeling Language.” RAML. N.p., n.d. Web. 11 July 2014. <http://raml.org/index.html>.

Leave a Reply

Your email address will not be published. Required fields are marked *