Simplifying the API design with RAML Traits

Facebooktwittergoogle_plusredditpinterestlinkedinmail

RAML has brought a revolution in API design for our REST services. With the new specification of RAML it’s quite easy to design our APIs with several RAML tags.
We will be here demonstrating with some of the RAML elements and Methods.

Also in this article, we will see how to use of the resource types features in RAML can eliminate redundancies in resource and the API design.

How can we design RAML for our RESTAPIs with resourceTypes ???    untitled

Before we start discussing on resourceTypes, let’s see what is actually a resourceTypes is ???

resourceTypes :- A resource type is a partial resource definition that, like a resource, can specify a description and methods and their properties. Resources that use a resource type inherit its properties, such as its methods.

What does that means???  untitled

As we know, there may be a lot of repetitive code, and may have
several methods that have similar descriptions, methods, response types
(for example error codes) and other information.

RAML has a feature called resourceTypes, or a templating engine that lets us to define a template (or multiple templates) and that can be used for multiple resources without repeating the code.

Let’s consider, we have resource /books and now we want to implement 2 methods in it (GET, POST). So, each of the methods will have a description, response types etc.
But now, let’s consider we have a requirement that, the methods (POST, GET) can also be used for other resources that we may declare for later use.

So, to make it simpler we will create a resourceTypes that can be used by any resource in the RAML file without repeating the code.

untitled

Adding new ResourceTypes  untitled

Here, we can see that we have created a template resourceTypes where we are defining both the methods GET and POST.

We are also setting description and response format for both the methods.

Also, we are referring the response example  from parameters :-

untitled

Now, we are defining a resource that will call and use this resourceTypes template.

Infact this makes easy to reuse the code, without repeating the method structure again and again for any other resources.

untitled

Here we can see that, the resource /books is calling and using the resourceTypes template.

So, now the /books resource will have both the method GET and POST defined in the template. Also, the response format is taking the response parameter from here.

Testing our API  untitled

API designer platform provides an option to test our APIs that we build in it. In the left side we can see a button called Mocking Service, if we on that button, the API will be ready for a mock test. You can see in the code, that our baseUri has been commented and a new mock Uri is generated.

untitled

So, to test the API, we need to hit Try it button in the right side, that display our API graphically, we will test our POST method first .:-

untitled

After we hit POST, we can able to see the response displayed as follows:-

untitled

So, after testing POST method we will be doing the same for GET method. Again we need to hit Try it button in the right side, that display our API graphically, we will test our GET method.:-

untitled

After hitting Try it button we will hit the GET button as seen below:- .

untitled

After we hit GET, we can able to see the response displayed as follows:-

untitled

Conclusion…..  untitled

So we can see that if we create a resourceTypes template in our RAML file, which contains description, methods etc, then we can easily use this template for any of other resources without writing a repeating code for methods or description.

So at the end I can only say that, let’s spread our knowledge and expand our Mule community. :)

Facebooktwittergoogle_plusredditpinterestlinkedinmail

Anirban Sen Chowdhary

Anirban Sen Chowdhary is an information technology professional currently working on Java/J2ee, Esb and Integration platform. For more information, please visit http://anirbansenchowdhary.com and you can also follow https://twitter.com/Anir37

You may also like...

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>