RAML is a powerful platform everyone should learn and practice. RAML stands for RESTful Api Modeling Language. It is, at its core, a language for designing RESTful and 'almost RESTful' APIs, using a human readable, text - based, powerful language. But it also an also an amazing productivity platform with all the tools necessary for managing your API, from design to sharing, including the build, test and document phases. In short with the RAML platform you can:
- Design your API
- Build your API
- Test your API
- Document your API
- Share your API
All in a very easy and hyper - productive fashion.
To start with raml....:
Just go to the RAML official website where you will find all the documentation and tutorials that will get you on track.
For instance the "For developers" menu offers two great 100 level and 200 level raml tutorials: after finishing them you will be "on-board"...
The next place to go is probably the Projects library. There you will find all kinds of amazing raml based or raml - related projects, most of them being hosted on github. I particulary like:
- The API Workbench: it's a powerful RAML I.D.E that exists as an Atom's plugin. Using it will boost your productivity in an amazing way.
- The API designer which will allow you to rapidly define finely tuned, raml - based APIs that can be read by both humen and machines
- The API Console [with a twilio api illustration] : an interactive API documentation that also exposes visually the structure of your API and the patterns it uses.
... and many more interesting API projects. The simplest way to experience the richness of it is to go there and browse a few api website: I bet it will fill you with excitement.
Design the API first allows me to visualise what it looks like before I ever start coding it. It exhibits the use of patterns and best practices or the lack of it. The RAML platforms gives some tools I can use to mock and test the services to see what the requests and responses looks like before I ever implement anything. This way I can fix design flaws before coding phase and optmise the project cost by dramatically reduce maintenance costs due to design flaws. Here is an illustration of what a raml - based api looks like:
#%RAML 1.0
title: Metrics Toolkit API
version: 1.0
baseUri: http://api.samplehost.com
types:
Metric:
properties:
uid:string
target:string
value:string
description:string
moment:date
example:
uid: "UDHUS-8595AA95s"
target: "database volume reading time"
value: "155.5 ms"
description: "Measure the average time to read a large data set"
moment: "2015/04/16"
/metrics:
get:
responses:
200:
body:
application/json:
type: Metric[]
post:
body:
application/json:
type: Metric
example: |
{
"uid":"HSJS-8595-DD",
"target":"Ldap lookup response time",
"value":"1.25 ms",
"description":"average time to perform an ldap lookup",
"moment":"2015/03/02"
}
/metrics/{uid}:
put:
body:
application/json:
type: Metric
delete:
responses:
204:
/metrics/categories:
get:
/metrics/categories/{categoryName}:
get:
As you notice, all the datas are returned by or sent to the API use json format, which is clearly specified at the body level of the various actions. We have defined a custom type that holds the relevant metric datas in a coherent way. Our API is not only readable by a human but we can automatically extract the documentation thereof or deploy a mocked testing service that will allow to test it in a significant way.
RAML is a young platform, but is already showing the level of quality that marks the greatest IT platforms. It perfectly stands the comparison with similar platforms such as swagger or API blueprint and it will probably become the leading platform of its kind.
