API specification in RAML and implementation in Mule


APIs are most important features in today’s digital world. Mule is one of the big names in this API world.

And in this API world RAML is the most powerful tools or specification  to design, built and test an API that can connect a complex interconnected design.

Enterprises today are adopting RESTful APIs for the digital economy with the changing world.
Previously WSDL and WADL were there to solve this issue of complex services and their design, but gradually faded out as it were either not enough to solve complex integration issues or were not adopted to meet their complex design.

After a while, Swagger, an API Description Language, also appeared as a specification to design RESTful APIs.
It was highly successful with it’s approach and now today RAML is gradually taking place in the same way and is more flexible.

RAML is one of the only API Description specification that have all feature of an API’s life cycle. One of the challenges that we face today with our old API is documentation and here RAML comes into picture with flying colors.

RAML not only helps to design the structure of an API but also helps in multiple documentation problems through the creation and maintenance of a single file and thus it not only makes this process easy but much efficient.

Mule supports RAML and it helps to implement the APIs designed  with the RAML in a very easy and simple way.

In this article, we will see how to use the RAML  with Mule ESB or simple in our Anypoint Studio.To use an existing RAML file with our Mule application, we need to have APIKit plugins in our studio.

APIKit converts a RAML specification into Mule ESB flows and is very useful if we are planning to implement the REST service in Mule ESB as our runtime platform. This is an open-source, declarative toolkit specially created to facilitate REST API. It enforce API-first development and encourage a good API implementation practices.

When we create a new APIKit project and click Finish, Anypoint Studio uses the imported RAML file to automatically generate skeletal backend flows, one for each resource-action pairing in theRAML file. Also, Studio pre-populates each of the flows with one or more message processors which perform“mock” activities based on the content of the example response included with each resource-action pairing in the RAML file.

RAML in Our Anypoint Studio

Let’s consider, we have designed a RAML specification for our API in API designer as follows:-


We need to click Export as shown above.We will see our RAML file is downloaded in our local system as a Zip file. We need to extract the file and use the.raml file generated.

In Anypoint Studio, We create a new Mule project as below:


Let’s give the project name as TestRAML, and add APIKit component in the project and refer our RAML file from our local system, where we downloaded the file from API designer:-


Once we click finish button, we can see Mule has created the project and flows are automatically created based on our RAML file we created.

Routing of requests to Mule flows are performed by a this APIKit router :-



If we go into the code, we will find the RAML file has created different types of flows and exception strategy with the APIKit and we can see different exception defined and it is automatically generated by APIKit plugin.

Mule Studio automatically generates several global exception strategy mappings that the Main flow references to send error responses in HTTP-status-code-friendly format.:


APIKit facilitates RAML-based error handling by generating global exception strategies for the most frequently to handle the most widely-used HTTP status code responses.

If we see our code thoroughly we will find that the APIKit plugin has divided the flow into 2 parts as our RAML file described.It contains the main flow which exposes the API with the HTTP listener and the APIKit router route the request to flow called get:/books:api-config. Since, we only have one resource defined in our RAML, it is routed to only one flow created:


Testing Our API

We will be running our Mule project as Mule application .To test the API, we can see APIKit Console has started.

We can see the APIKit console in our browser after putting the URL there. Now, we are ready to test our API in the browser with API console:


So, finally after filling the query param and then hitting the GET button we get our response:


As we can see it is very very easy to create a RESTFul apis in our Anypoint Studio with a RAML file. With the help of APIKit plugin it gets very simple in designing and testing our APIs.

APIkit is an open-source project that greatly simplifies the development of RAML-defined APIs with Mule flows and have lot of flexibility. The project consists of Maven- and Eclipse-based tooling which can be used from MuleSoft’s Anypoint Studio IDE and it becomes very easy to implement a complex API in Mule extracted from the RAML specification design.

Another important features of this APIkit projects is that it is  packaged with a interaction console that is similar and dynamic like API Designer tool for testing the API allowing to interact with the API and the documentation developed within the RAML design .

I hope you like this article on implementing RAML in our Anypoint Studio and I am looking forward to see your feedback in comment section.



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

1 Response

  1. Animesh Kumar says:

    Very good article for people who want to get an understanding of the ApiKit functionality in Mule Anypoint Studio with respect to RAML.
    Thanks @Anirban for taking time to spread the knowledge. Keep writing good articles.

Leave a Reply to Animesh Kumar Cancel 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>