Almost exactly a year ago, the RAML workgroup released the first public version of the RESTful API Markup Language spec, RAML 0.8, along with some tooling and a website. It's been one heck of a year, in which we saw massive adoption across users and companies large and small; active discussions online and at conferences and meetups; a community of tool developers on raml.org and on github with a vibrancy we could only dream of; and virality: developers leveraging other developers' work in a chain of value.
A Deep Dive into IoT, RAML, and Robot APIs
I've been thinking a lot recently about the Internet of Things (IoT), in its numerous variations. Like all popular memes, it's used and abused in numerous ways. But a core concept is to connect to the network things that are not traditionally thought of as connected – toasters, locomotives, roads, even network devices themselves (think Software Defined Networking, or SDN). Some of those things are dumb, but useful: temperature sensors, pedometers, trip switches, lightbulbs. But I wanted to think on the other side of the spectrum: what are some things that are smart, or at least that can do a lot more than just turn on or off or send out a reading? Where can I find truly creative ideas for interesting things that are even more interesting when networked?
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?