New RAML (RESTful API Markup Language) Web Tooling
Originally authored by Uri Sarid
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.
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.
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).
(Note: Opinions expressed in this article and its replies are the opinions of their respective authors and not those of DZone, Inc.)