Designing REST APIs with RAML(Part 3)

By Anirban Sen Chowdhary

In previous slides we have seen how to design a REST API with RAML. We have also designed the API and introduced several RAML tags like Headers, Query parameters as well as designing with method like GET.We have also seen how to use POST method and uri Parameters.If you are still wondering where to get the previous slides to begin with, you can get it here :-http://www.slideshare.net/anir37/designing-rest-with-raml andhttp://www.slideshare.net/anir37/designing-rest-with-raml-part2

Here in this slides we will be demonstrating with some other RAML elements and Methods.

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

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???

As we know, there may be a lot of repetitive code, and may haveseveral 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.

Adding new ResourceTypes

Defining a resourceTypes :-

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 :-

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.

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

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.

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 .:-

After hitting Try it button we will fill the request body with the example button and then will hit the POST button as seen below:- .

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

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.:-

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

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

Conclusion…..

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.

Thank You