Designing an API with RAML Specs Part 1

Facebooktwittergoogle_plusredditpinterestlinkedinmail

REST is also called as representational state transfer.
The REST API lets us to interact with anything that can send an HTTP request.
REST APIs are one of those which are very easy to create and design and it supports various methods like GET, POST, PUT, DELETE etc to perform various types of operations.

In Mule, we can create and design a REST service various ways.
But, with the new specification of RAML, it became quite a easy task to create, design and test our APIs as per our requirement.

Before we start, we will actually look into what RAML really is.

RAML which is also called as RESTful API Modeling Language, helps us to manage the whole api lifecycle starting from it’s design, develop to sharing.

It is basically build on top of YAML for describing RESTful APIs and provides all the information to describe an API.

Advantages of RAML:-

  • RAML lets us see what our API looks like we you design it with it’s easy to read plain text.
  • RAML lets us to reuse the code and we also provide us the feature to visually verify our API looks, feels, and functions the way we want.
  • RAML lets us to design our APIs in powerful tools such as API designer and API workbench.

Reference :- http://raml.org/

Here in this post, we will be seeing various ways of designing an API with different RAML specs.

How can we design RAML for our REST APIs ???

RAML can be designed in API designer.

API Designer is a standalone/embeddable editor for RAML (RESTful API Modeling Language) written in JavaScript using Angular.JS. By default, the editor uses an in-browser filesystem stored in HTML5 Local storage.

API designer :- https://www.mulesoft.com/platform/api/api-designer

With this tool/editor, we can design our APIs and test it there itself using a mock service with the tool.

Designing RAML for REST API

So, we will be creating our first RAML in the API designer as follows.:-

untitled

The initial RAML file will contain ROOT section, which will describe the basic information of the API.

It includes API Title, API Version, BaseUri and all the BaseUri Parameters.

#%RAML 0.8 is the first line in the RAML and it describe the RAML version.

Now, we will add some more tags in the file like Protocols and Media Type:-

untitled

Protocols :- The protocols property MAY be used to specify the protocols that an API supports. If the protocols property is not specified, the protocol specified at the baseUri property is used.

Media Type :- The media types returned by API responses, and expected from API requests that accept a body, MAY be defaulted by specifying the mediaType property. This property is specified at the root level of the API definition.

Both the above properties are optional though.

Adding Resources:-

Resource :- Resources are identified by their relative URI, which MUST begin with a slash (/).

untitled

Let’s add a resource say /product . So, 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 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
* DELETE
and many more.
We will be seeing GET performed on our resource.

Methods also contains the properties like displayName and description

Adding GET Methods:-

As you can see here, we applied GET method on our resource /product:-

untitled

Though description is an option properties for methods, but it is RECOMMENDED that all API definition methods include the description property.

Adding Headers:-

We can add our custom headers in our API:-

untitled

Headers :- The headers property is a map in which the key is the name of the header, and the value is itself a map specifying the header attributes. It contains properties like displayName, type, required, example etc.

Adding Query String:-

We can also add our query parameters in our API:-

untitled

queryParameters :- The queryParameters property is a map in which the key is the query parameter’s name, and the value is itself a map specifying the query parameter’s attributes. It contains properties like displayName, type, required, example, description etc.

Adding Response:-

We can different response based on status code :

untitled

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.

untitled

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.

That’s it !! Our API is ready to go with RAML specs!

 

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 the next part I will show to design our APIs with other methods and specifications.

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

 

Facebooktwittergoogle_plusredditpinterestlinkedinmail

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

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>