Over a million developers have joined DZone.

RAML: Designing a Simple API

DZone 's Guide to

RAML: Designing a Simple API

In this tutorial, learn how to design a simple API by working with the RESTful API Modeling Language, complete with code and screenshots to illustrate the process.

Free Resource
  • The following procedure covers how to design and implement an online REST service and consume that service. The procedure describes an example API that has only one resource; for simplicity, the user details were hard-coded you can also implement a corresponding backend connection to get the actual user data based on the inputs.

Creating the Sample Project Name User_Information

Once you have started your Anypoint studio, click on File, New, and Mule Project as shown in the below screenshot:

Create a mule project

Enter the Project Name as `User_Information` and then click on Finish tab.

Project Folder Structure

Generating a Sample RAML Definition API (Creating sample.raml)

Right click on project (User_Information), click on New, click on RAML API Definition, and then enter the file name as "sample." Click on finish.

Creating Sample.raml file

As you can see in the below screenshot, a sample.raml file as been created with title "Sample AP."

Sample API

Configure a Service endpoint and document section using baseUri and documentation properties at the root level of RAML file, as shown in this screenshot:

Service Endpoint and documentation

baseUri: https://www.tirapareddy.com:8081/api

- title: Home Page for Sample API
content: |
This example documentation forms part of a tutorial for a 
[RAML Turorial](https://docs.mulesoft.com/api-manager/design-raml-api-task) article.

Create a sample user-example.json response JSON file.

"name":"Tirapa Reddy Tondapu",
"company":"Eidiko Systems Integrators",

Create a sample resource to get user details as shown in the below code block.

  description: Retrieves details of a particular users
          example: !include user-example.json

Now we have created a resource named "userInfo" that can be used to retrieve particular user information.

Generate Corresponding Flows for This Resource (userInfo) From the RAML File

In order to generate corresponding flows for the above userInfo resource we need to right click on sample.raml==> click on Mule ==> click on Generate flows from RAML as shown in the attached screenshot:Generating Flows

As you can see in the above screenshot once you click on "generate flows from RAML", it will generate sample.xml mule cofiguration file containing below items along with the  below attached HTTP listener  congiguration(i.e the application is running at hot "localhost" and post:8081)

  1. APIKit Router.

  2. APIKit Console.

  3. userInfo resource flow.

  4. Global exception strategy.HTTP Listener Configurations

Running The User_information Project

Right click on the project "User_information" then click "Run as" and then click on " Mule Application."

Once you click on "Mule Application," the project will be deployed as shown in the attached screenshot.


As the project has been deployed, now it is accessible from http://localhost:8081/console once you browse this URL you will be able to see the below API details:

Sample API Console

You can now access the API resource "userInfo" by clicking on GET and the providing any id value as shown in the attached screenshot:

Final Output page of Sample API

You can also see entire source code at https://github.com/tirapa-eidiko/RAML_User_Information.

Thanks & Regards,

Tirapa Reddy Tondapu

raml ,api ,integration ,tutorial

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}