RAML Open Specification And Tools Released To Aid In API Design

A new  API description language is looking to help out where many modern APIs get stuck: at the design phase. Officially announced, today, the RESTful API Modeling Langauge (aka RAML) offers a format friendly to both humans and machines. It also centers on re-use of results within responses. Like other description languages, it also offers the potential for post-design benefits such as streamlining Documentation, enabling interactive consoles and generating client libraries. Though not formally announced at the time, the format was originally revealed earlier this month. RAML is an open specification that's spearheaded by the recently formed RAML Workgroup. The workgroup's founding members include representatives from Box, Intuit, PayPal, AngularJS and Mulesoft (disclosure: the workgroup's co-chair Uri Sarid is the CTO of Mulesoft, parent company to ProgrammableWeb.com). In making RAML an open specification, the workgroup has paved the way for third parties to create their own implementations or incorporate RAML specific support into existing tools so long as they abide by the workgroup's guidelines regarding use of the RAML brand and trademarks.  For example, development tools like Webstorm or Sublime can incorporate support for RAML in such a way that eases  developers' consumption of APIs that are already described in the modeling language.  The workgroup has also released its first implementation of RAML; a parser whose Source Code is available under the open source Apache License, version 2.0. In addition to the RAML parser, the RAML projects page shows several RAML-compliant projects that were released today by Mulesoft under the open source CPAL license. The tools include the API designer,  API console and API notebook, all of which can be seen in a demo video showing the RAML format in action from initial design to incorporating JSON schemas to creating and sharing sample calls. When RAML first surfaced in advance of today's announcement, some complained in a Hacker News thread that it's not RESTful enough in its approach. This common argument within the API community is addressed on the about RAML page:

We say "practically RESTful" because, today in the real world, very few APIs today actually obey all constraints of REST. RAML isn't strict: for now, it focuses on cleanly describing resources, methods, parameters, responses, media types, and other HTTP constructs that form the basis for modern APIs that obey many, though perhaps not all, RESTful constraints.

Similar criticisms have been made about ProgrammableWeb's list of REST APIs. There's a balance between adhering to "true REST" and being pragmatic. Any API description language needs to be cognizant of how APIs are used today. The truth, as REST zealots and the RAML group point out, is that few APIs are truly RESTful. There are other formats with similar approaches to automated API documentation. WADL is perhaps the oldest, but "carries the weight of XML and doesn't carry forth the simplicity of REST," RAML co-chair Uri Sarid said. Perhaps the most telling detraction of WADL is that API thinkers keep passing it up in favor of new formats. Swagger is perhaps the format with the most traction at this time, spinning out of Wordnik earlier this year. In July, Romin Irani took a deeper look at Swagger. Apiary.io takes a design approach with its paid blueprint service, which entered beta in mid-2012. Blueprint is simple Markdown with special syntax for describing APIs. Like Swagger, it is more closely resembles documentation than code, so is more likely to be part of the documentation workflow. As with visual design, API design benefits from common patterns. This is where RAML diverges from other description languages. RAML makes API design patterns a major factor of the format. "It allows you to externalize them and reuse them," Sarid said. "As a result, you can immediately make out the structure and the various elements of the API." RAML parsers understand both XML and JSON Schemas, declared inline or as separate includes. It may seem like everyone has their own standard for describing APIs (Google created a description format for its 100+ Google APIs). While it's natural to yearn for a single standard, it is still very early in the mainstreaming of APIs. Different approaches are what have enabled APIs to progress quickly. The simplicity of REST (or RESTful or even REST-ish) and JSON made the 10,000 API milestone possible. Reaching one million will very likely involve a variety of structured approaches. Adam DuVander is Developer Communications Director for SendGrid and Contributing Editor of ProgrammableWeb. Previously he edited this site and wrote for Wired. You can follow him on Twitter.

Be sure to read the next Best Practices article: PW Interview: Scott Gimpel Founder and CEO FantasyData.com