Designing an API with RAML Specs Part 2


In previous blog post 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 blog post to begin with, you can get it here :-

Here in this blog post we will be demonstrating with some other RAML elements and POST 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 POST Methods:

Here we will design 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.


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



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 and you can also follow

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>