Guest Post: MuleSoft Unleashes RAML Web Tooling

Uri Sarid is MuleSoft’s CTO, as well as a member of the RAML Workgroup. The posting below originally appeared on the MuleSoft blog.

I’m excited to announce that we’ve recently made available to the RAML community a new API Designer, API Console, and API Notebook, built around a new RAML JavaScript parser released as part of the RAML workgroup. All of these are available under open-source licenses, and all may either be downloaded and used on your own site or are hosted as part of the APIhub.com service. You can find them on the projects page of RAML.org.

How did we get here?

I’m extremely excited by the opportunities APIs unlock for our customers and for us all. APIs enable data exchanges, and therefore enable creativity and innovation. But that potential is crippled if the APIs themselves are obscure, difficult to consume, and inefficient. At MuleSoft, we believe the key is to bake in good design from the beginning: start with the consumption experience, the “APX” or Application Programming eXperience, craft it purposefully for your intended audience, and iterate on the design until they’re not only satisfied but truly delighted. Then you know your API strategy only depends on executing to that design in order to succeed.

Reza Shafii, my colleague in charge of our API platform, will discuss this execution in his next post. But I’ll focus here on the design, and specifically on the design of RESTful APIs. The key is to make the API itself expressible so easily, so cleanly, that designing and redesigning is incredibly quick and efficient. When iteration cycle times are expressed in hours rather than weeks, there’s time even in urgent projects to get the design right. And if patterns of APIs can be developed and reused, or even borrowed from existing patterns, design time is further reduced, often dramatically, and the complexity of your APIs doesn’t increase as their numbers grow.

How do we get to such quick, clean, pattern-driven design? Enter RAML, the RESTful API Programming Language, developed by the RAML working group (in which I’m a member) and released last month. You can read more about it on RAML.org. I believe it’s the first time that RESTful APIs are expressible in a format that’s as simple and compelling as REST itself. And it explicitly promotes the development and reuse of patterns: resource types, traits, schemas, and security schemes. It starts with YAML, which itself is optimized for human readability, and layers on top of it an HTTP resource- and method-oriented semantics.

With RAML as a natural, organic base ingredient, we didn’t need to add much more to get a potent RESTful API design solution: we created a web-based API Designer based on a simple editor with hinting built in, and an interactive web-based API Console that documents the API as you design it, all built around a JavaScript RAML parser that serves as a reference implementation of the language. Once the API is implemented, for real or through a mocking service we’ll soon release, you can use the API Console to try it out interactively, and use the new API Notebook we created to script together API usecases for one or multiple APIs right in your browser and share them with others.

Digging in a bit more: the API Designer is an editor that knows about RAML. As you type, the editor both auto-completes valid RAML at the point you’re typing, as well as showing you a “shelf” housing all the RAML elements allowed at that point, and syntax-highlights everything. So if you prefer to type it’s optimized for you, and if you prefer to click and insert it’s optimized for you. As you’re entering your RAML, the parser runs in the background, showing you any errors and explaining how to fix them. On the right side of the Designer we’ve embedded the API Console in its narrow mode, showing you the API right as you build it, as fully-interactive documentation and even a Try-It button. Try it? How? If you haven’t yet implemented your API, you’ll be able to “try” right away a mocking service that adheres to the API you’ve just defined. That’s coming very soon. The API Console is the same view your API consumers will see, so you’re truly experiencing what they’ll see first hand.

The API Notebook is a different beast: it’s a great way to play with implemented (or mocked) APIs, scripting together usecases using JavaScript right in your browser. It uses a proxy service so you don’t run into cross-domain limitations, and it auto-generates a JavaScript clients on the fly by just pointing it to the URLs where the RAML API descriptions live. Because it has the same kind of auto-complete as the API Designer, you might even get by without reading the API docs at all! You can save your experiments and share your notebooks with others, who can run them or fork and launch their own experiments. (A cool note: notebooks are saved by default as gists in github, and their format is just github-flavored markdown with fenced code blocks. Talk about portable!) API publishers can use these as usecase documentation, but they can also crowdsource the documentation much as MySQL did a while ago, when users’ comments on the official docs formed a rich bed of solutions to real-world cases.

We built these tools for use in our Anypoint Platform for APIs, but we knew they’d be useful for the entire API community, so we’ve just released them under open-source licenses for anyone to use in their own projects. We’re strong supporters of the design-first approach to APIs and of RAML as a way to achieve that: simplifying and accelerating API design and consumption, and promoting more consistency across APIs, should help all of us in the API space to realize all this potential. We hope you enjoy using them as much as we do. And please, do let us know what you think, and whether you’ve found them of use in your projects. Perhaps you’re building some tooling too, or are looking for an opportunity to put your creativity and ninja skills to great use in this space? If so, let’s talk! (Comment here, or tweet to @MuleSoft or #RAML or @usarid, or email).