RAML (Rest API Modeling Language: http://raml.org) allows you to design rest API endpoints and pretty much everything else related to them, in a single source of truth document. Now, to be fair, larger APIs may extend across several files, not just one, but generally speaking you can think of it as your single source of truth "bundle".
Why single source of truth? Simple really, you can describe a Rest API including the endpoints, headers, request body, one or more response bodies and headers, and document every aspect of every thing that makes up a request and response in succinct detail. But once you have an API endpoint described.. what can you do with it? The file alone looks nice, it's easier to read than most other formats, such as JSON based formats, and very easy to construct. The API Designer (https://github.com/mulesoft/api-designer) also has a built in code completion editor and a side panel documentation generator the builds up the documentation as you build your API. These things make it incredibly user (er..designer) friendly, but also make it quick to see how your API is progressing.
Does this mean you are locked in to this designer tool and the documentation you see? Nope.. not at all. The API you design is stored as a file. Actually, let me point out that the initial API Designer tool uses the HTML 5 Storage API to store the files internally in the browser. There are forks to this project for storing files in a mongo database, but the one I personally use is one that stores files on disk (https://github.com/arthurtsang/raml-store). This allows you to run the designer locally on your development machine, wherever, and use a local file system. I set this up to point to the same file system where my git repo for my own project resides, so that I am modifying a git controlled set of files and can easily commit changes, pull others using the same git project, etc.
"Great..so with a little bit of work I can create RAML files, share them with a repo and team members.. that's all.. something pretty to look at in their fancy design tool?". Nope.. there is a lot more, and you can see just a small sample of the projects on the http://raml.org site under Projects. The key is to be able to use the RAML file in other ways, such as separate document generators, code generators, test generators, etc. From the project list you can identify several projects for consuming the RAML file(s) in some manner and doing something with them.
Before I go further, I'd like to point out that the RAML spec currently is 0.8. There is a 1.0 draft in the works that will be addressing many of the issues and feature requests the community has requested over the past year or so since the 0.8 has been ramping up adoption. There is no specific time frame for when the 1.0 spec will be made available, but much like a video game, I'd rather wait longer and see a solid 1.0 release spec, than a rushed spec to get it out sooner.
RAML allows for the inclusion of request and response body (entity) definitions in the way of JSON Schema or XML Schema. RAML being a spec, it does nothing more than allow you to define these definitions either in the RAML file itself, or as includes to external files. That alone is pretty nice.. as you add XML Schema or JSON Schema in the API Designer, you can see the on-the-fly generated docs provide links to display the actual schema, making it easy to access the definition a given request or response body requires. You can even specify media types for each request, allowing for different schema definitions depending on the media type for the request or response.
Ok.. so you're still asking what can you do with RAML. It's pretty and all in the designer, but we want to use it for more than just looking pretty and on-the-fly doc generation. The good news is.. it's just a file (or maybe a few depending on how you design your API, how large, etc). So you can easily pass the RAML file(s) to a tool and consume it. RAML is just YAML with some specific requirements around formatting for REST APIs. The great thing is, the RAML team put together a few projects to help you parse the RAML file. In particular, as a Java developer, the Java RAML parser can load up a RAML file and allow you to navigate the RAML tree structure. This could be used to do whatever you wanted with RAML, such as build documentation however you see fit, SDK code, etc.
There is one project in particular, however, that I want to highlight. The project is raml-generator (https://github.com/mulesoft-labs/raml-generator). It's loosely based on the raml-client-generator (https://github.com/mulesoft/raml-client-generator). The key difference is that the raml-client-generator is an all encompassing project where you would add your generator code to the project itself.. and raml-generator allows you to "embed" the use of the generator in your own project, outside of the directory structure of raml-client-generator. Both projects are built with NodeJS and NPM. Raml-generator is even pushed to the Node repository so you can simply require() it in your code and use it.
The benefit of this one tool is that you can use it to generate just about any output you want from RAML. It uses JavaScript to parse the RAML object, and seamlessly snaps in the use of Handlebars.js templating engine to allow you to quickly and easily build templates + NodeJS modules and code to build generators for any purpose.
What sort of generators? How about client side SDKs, server side API processors, documentation, test code and more. While it does require you to understand NodeJS to some degree and Handlebars.js templating a bit, both are not terribly difficult to learn.
I am going to have a follow-up HowTo post around the raml-generator tool. I'll try to elaborate on the setup of the tool, how to use it in your own code, and how to build a generator from Handlebars.js templates and helper functions as well as different ways to use templates and generate file output from RAML, as well as thoughts on CI/CD integration.
