Laura Heritage is the Director of API Strategy at SOA Software and an Open Group certified Master IT Specialist in Application & Integration Middleware. She has over 16 years of experience working with enterprises around the world establishing SOA and API strategies.
Steven Butt is a Senior Software Engineer working on cloud platforms at MuleSoft. He moonlights as an advocate for API cleanliness.
As a web platform engineer I found myself very excited when the RAML API definition language first came onto the scene. Finally there was simple programmatic method to design and document APIs and then use that same design to drive mockups and real implementation. However, like most engineers at companies with existing Java web applications in production, I already own a large suite of active public and private APIs that need documentation, updating, and quite often new features added. How was I supposed to go from my existing Java code (implemented with Jersey JAX-RS) to a complete set of RAML files with full API definitions, schemas, and examples? Manually typing out RAML files was not the best option due to the large number of existing API resources. Believe me, I tried.
I think it’s worth starting this article by mentioning Why am I writing it. I've been working with APIs for a long time. I'm talking about back when building an API was painful, and testing was close to impossible. Since working with RAML, I’ve discovered an amazingly vast amount of tools available, thanks to its community. One tool in particular enables me to grab any existing RESTful API (built or documented/proxied with RAML), and start utilizing it without having to install any software, tools, or libraries on my machine. More importantly, I didn’t even need research anything before using the API (I didn’t even have to read the API documentation).
What is it
Anypoint API Notebook is part of MuleSoft's Anypoint platform for APIs, and it could be considered as one of the supporting last steps in MuleSoft’s "The Agile API Build Lifecycle: Validate or not."
MuleSoft releases the first NodeJS RAML implementation and its name is Osprey.
I'm really happy to announce that we've made Osprey available to the RAML community. Osprey is a NodeJS-based framework conceived with the mission of developing RESTful APIs in a really easy (and IMHO happy) way. Since it's based on the RAML standard, it responds to a conventional way of defining, creating and documenting RESTful APIs, which turns to be really convenient, especially because:
We're excited that RAML is catching on, the community is growing, and developers from all over the world are building and publishing new and exciting tools for everyone to use and contribute to. We have published two of these tools (details below) on the RAML projects page this week, and hope you get a chance to try them out.
RAML to HTML
An easy-to-install and even-easier-to-use command line interface that takes a RAML file and generates documentation in a single HTML page (the only dependencies are bootstrap and jQuery). The installation and usage instructions can be found here, but due to its simplicity, I can just copy into two single lines:
npm i -g raml2html
raml2html example.raml > example.html
The generated page is clean and smart:
With the recent release of the RAML Mocking Service I took a couple of minutes to try it out and put together this walkthrough. I hope you find this useful. What is it? A service capable of reacting to http requests by returning the correct responses based on your RAML configuration (it will be a no brainer to use this if you follow the example on this thread). How can I access and use it? It's already integrated with the API Portal and working directly as part of the API Designer's Console. Show me the code! Hold your horses, first a quick "project" description. Let suppose you are trying to write the API for some e-commerce product catalog. Now, let's focus on the "Product" resource, which will have an Id, Name and Price. That's it. Let's create the API that will allow us to retrieve the list of products and to create a new one. Let's start by writing a minimal and valid RAML file, and add the resource and a first empty response.
Federico Bongiovanni is a Development Engineering Manager at MuleSoft.
While I was visiting Brazil last week at the MuleSoft summit in Sao Paulo, somebody mentioned to me that SoapUI was now supporting RAML. I took a look and quickly landed on this blog post from Ole Lensmar, the creator of SoapUI. My first reaction was to be totally amazed. SoapUI is my favorite tool for testing web services. So I proceeded to install it, expecting something to not work at first try… but it worked seamlessly. After following the installation steps, in 5 minutes I had the RAML support just where I expected it.
Great! After that, I went ahead and imported a sample RAML file. Instantly I got the structure and skeletons for:
- all the resources
- all the actions
- all my API!
It was respecting everything that was declared in my API spec. Even the examples and media types… so quick, so easy.
Uri Sarid is MuleSoft's CTO, as well as a member of the RAML Workgroup.
The posting below originally appeared on the MuleSoft blog.
How did we get here?
On behalf of the RAML Workgroup, I am excited to unveil the RESTful API Modeling Language today as an open spec. This project’s been under development for quite some time, while we’ve been battle testing it and utilizing it to improve our own internal APIs. As we began socializing the spec for feedback from several API experts, we were humbled to see mounting interest from folks who got deeply interested in collaborating on the direction of the spec. As a provider, an API is the capability you offer others (inside your company or outside) to derive your value, to add theirs, to create and realize opportunities. As a consumer, an API is what you build on to realize the provider's value or to generate even more value. So an API is a contract between provider and consumer, around an interface. Both the provider and the consumer have to build around a common definition for that API. The success of the API depends on how well this contract works, as well as how well it’s implemented on both sides. RAML is a language for expressing that interface, that contract, optimized for the users of the contract: the consumers and the providers.
There’s a saying that goes something like: to err is human, to really screw up big time takes a computer. But if you really want to have some fun, connect that computer to another computer, and you soon have a veritable nuclear chain reaction. The key to unlocking this energy? The lowly API, a programmer’s best friend, the little enabler that placed Google Maps in the center of mashup mania, drove the Ajax revolution, and is now generating over half of SalesForce.com’s revenues.
So, you’re a SaaS vendor and you want some API action for your service? Eager to get your share of the API Economy? Think you can just throw some @WebService annotations in your code and, blam-o, you’re now a card-carrying member of the API league? Not so fast…