15 Temmuz 2014 Salı

RESTful API Modelling Language, RAML and beyond.

When you want to provide an API to your customers, no matter how complex your backend code might be, you can design your API as a series of  Restful web services to ensure simple information exchange in an organised manner.
Although it may be easy to design Restful web services for projects offering limited number of APIs
as your service interface complexity increases, it is a good idea to consider better alternatives for your Restful API presentation, this is where RAML (http://raml.org ) comes in to the picture.

RAML, RESTful API Modelling Language, is built on YAML, and it is a nifty way of designing your API model for complex service structures.
RAML is strict as an old school teacher, and picky when it comes to syntax. But it is actually a good thing because this picky nature of RAML lets you design APIs that are human readable, standardised and easily “parsable”. 
By parsing a RAML document you can create HTML API documents with a single command which then can be used as a source of reference for your API users. Since, you used a solid model for your API architecture, generated Apı document will be sufficiently detailed and faithful to your design.

API designer for RAML (http://api-portal.anypoint.mulesoft.com/raml/api-designer) is an IDE like web based api designer application which you can use to develop your RESTful APIs as well as RAML documents.  You can also grab your very own clone of the designer from GitHub (https://github.com/mulesoft/api-designer)

To get started you can find a good tutorial on http://raml.org/docs.html on RAML API design. 
First things first, RAML parser checks your RAML version before executing so make sure to include the RAML version in your document. 
The root section of your document is where you define general information of your API such as title, version, baseURI , Schemas , ResourceTypes, traits and other information which will be used on the rest of your document can be described here.
Resources section defines the behaviours of your path(s) and resources. This is where you define your parameters, methods , security and include your predefined Schemas etc... in your resource.

While designing your API, the API designer also does error checking and offers feedbacks concerning parameter values, methods etc... which make your learning experience less painful. Clicking the “Mocking Service” button which is on the right hand side of the design page gives you a fancy presentation of how your API document may look like as an html page . Since the API designer uses a RAML parser while converting our design to html format, if there are some errors in the design document, some parts of our design appears to be missing, this is an other way to make sure that our RAML design or syntax is correct.

Remember the fancy HTML page ? When you are satisfied with your design, RAML2HTML (https://github.com/kevinrenskers/raml2html) is a good tool which you can use to convert your .RAML document to html. After you install the tool,  converting your RAML document to html is as simple as running the following command: raml2html example.raml > example.html
Kevin’s tool creates a beautiful looking HTML page presentation of your API design which can be used as your api document to be presented to your customers or users.

For our current project we need to use a considerable large number of REST APIs. RAML helps us design these APIs in a consistent way, plus basically generates our design documents in HTML for us.  But why stop there? So we grabbed  our favourite RAML parser (a good RAML parser https://github.com/raml-org/raml-js-parser ) and started writing our own code generator for both the client side and the server side in javascript and nodejs.

By parsing our own API design from the RAML we generate the web server code according to path , query parameters and parameter definitions. 
We then create our client code which is created with the requirements of our resource. We embrace the modular approach while generating  our code where each resource has it’s own function. Test functions are created in jasmine along with the generated code.
Code generator  also cross checks our generated server and client code back and forth after creation tom make sure everything works perfectly.

It is a work in progress, but by the time it is done it will be able to generate RESTful services code for both the client from our RAML documents and the server side which will even be tested back and forth during creation.
Generated service declaration functions will be standardised and it will be perfectly aligned with the API definition reducing the complexity of the overall code. 

So at the end of the day, we used RAML to Design our Restful web-service APIs,  document our API functionality and even used it to generate our server/client code for us.

Kivanc Gulbas & Nilufer Bidik