MuleSoft has just announced the release of three RAML-based tools for designing, evaluating and testing RESTful APIs.
RAML comes from RESTful API Modeling Language, and is a human readable and machine interpretable language for specifying and documenting APIs. RAML is based on YAML, being compliant with version 1.2, and helps designing RESTful APIs, encouraging the discovery and reuse of API patterns, leading to higher API quality by relying on standards and good practices.
The web-based RAML tools released by MuleSoft are:
API Designer: a web editor for creating and sharing API specifications. It suggests what elements can be used at some point and signals eventual errors in the RAML document created with it. Following is a snippet of a books API with a get method, which returns all the books written by the same author, and a {booksId} section with a method for getting a specific book and delete method for removing a book from the collection:
As it can be seen from the snippet, the API definition can make use of schemas which are used to define more complex resources. Also, at the bottom of the editor there are shown the methods, parameters, resources and other elements that are available at any point in API definition process.
API Console: used to graphically visualize and evaluate an API as it is created, outlining the document’s structure and patterns. The next snippet shows how the console looks like for the demo API defined above, including the books try section useful for test running API calls:
API Notebook: a JavaScript console for testing an API, either by itself or in a combination with other APIs in mashups. It can be used to generate mockup clients for APIs described in RAML and start using them.
The development of RAML is supervised by a working group including Uri Sarid, CTO at MuleSoft Inc, Ivan Lazarov, Chief Enterprise Architect at Intuit, Bill Scott, Sr. Director of User Interface Engineering at PayPal, Miško Hevery, AngularJS Project Founder, John Musser, Founder of Programmable Web & API Science, Peter Rexer, Senior Platform Product Manager at Box, and Kin Lane, Presidential Innovation Fellow at the Department of Veterans Affairs. Commenting on this working group and their plans with it, Sarid told InfoQ:
RAML is in its early days, and we want to make sure it evolves efficiently to solve today's urgent API design and description needs, without getting bogged down by overly-heavy formal governance. To that end, we've formed a workgroup of like-minded individuals from leading companies that place great value on APIs, and this group together with input from the community will drive RAML forward. The members can be found on the raml.org website. We'll adjust the membership over time to keep the group fresh and active, large enough to benefit from a variety of perspectives and small enough to stay nimble and focused on the goals. We invite the community to join in an open, vigorous discussion based on real-world, practical concerns as well as longer-term strategic goals.
On the future of RAML, Sarid added:
We think RAML already addresses many of the current issues faced by providers and consumers of practically-RESTful APIs, but by no means all of them. For example, we've not figured out how to capture the dependencies between input parameters such as the requested fields and output data such as the fields present in the response body -- or at least how to do so in a clean, powerful, intuitive way consistent with RAML's design goals. We're also not satisfied at this time, for JSON-based APIs, with just leaving the body representations to be characterized by JSON schema; they've not garnered nearly the broad adoption of XML schema, and they may not serve the needs of the RAML community as well as something else, perhaps. And looming ahead of us is the bigger question of the remaining REST design constraints, specifically hypermedia. Had we restricted RAML to purely-RESTful APIs, it would have 1) not applied to almost any existing APIs, and 2) not been feasible for most API initiatives to adopt today. So we're starting with the basics of REST APIs -- resources, methods, parameters, and bodies that need not be hypermedia -- and will evolve from there.
RAML is currently version 0.8, the complete specification being available on GitHub at https://github.com/raml-org/raml-spec. Also, a RAML parser written in CoffeeScript is available.