Designing REST APIs with RAML(Part 2)

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

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

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

We will go back to our API designer where we designed our previous API and start with a new resource and new methods

Adding new Resources

Let’s add a new resource say /book . So, again we will have a resource named product which will also act as a sub url of baseUri.displayName :- The displayName attribute provides a friendly name to the resource and can be used by documentation generation tools. This property is OPTIONAL.description :- Each resource have a description that describe the resource. This property is OPTIONAL.

Adding uri param

Here we can see we have added an optional uri parameter which will filter the api on base of name.The uri parameter has the properties like displayName, type, required, example etc.

Adding Methods

Now we can add methods for our resources.

methods :- methods are operations that are performed on a resource.There can be several methods applied on a resources such as :-

* GET* POST* PUT* DELETEand many more.We will be seeing GET performed on our resource.

Methods also contains the properties like displayName and description

Adding POST Methods

As you can see here, we applied POST method on our resource /book

Here we can see that the POST method takes input in the body section.We can refer the body input with schema or with example or with both.Other properties of formParameter are description, type, required, pattern and example.

So, here in our resource /book, we can access it using it as a sub url /book or can add the optional uri param name such as /book/{name}

Adding Response

We can different response based on status code :

Responses :- A resource methods may have one or more responses.

Responses may be described using the description property, and may include example attributes or schema properties.

Responses must be a map of one or more HTTP status codes, where each status code itself is a map that describes that status code.

In our example, we have mapped 2 responses for status code 200 and 404 respectively.So, these response will be generated as per the status code.

We can see at right side of our API designer, where preview of our API is displayed and the preview gets updated everytime we change or update our code.Here we can see the description, structure of our API and also the description of elements we have provided.

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

After hitting Try it button we can see protocols, uri param field that we need to fill before we hit the service. We can see it is already filled with example values.

We need to hit the POST button to hit the service that is designed with POST method, but before that we need to fill the BODY with example request:-

After we hit the POST button, we can see that the response is generated with status code 200

We can click the save button and save our API design in API designer.

Conclusion…..

So we can see it is very very easy to design and create a RAML file for our RESTful api.The API designer helps us greatly in designing as well as testing the API we create.In this we have seen how to design a REST api with POST method a uri parameter.

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

Thank You