Share on FacebookShare on Google+Tweet about this on TwitterShare on LinkedIn
Profile photo of Srivatsan Sundararajan
Srivatsan Sundararajan
Quality Assurance Manager for MyEclipse and Webclipse.

What is RAML?

RAML stands for RESTful API Modeling Language. It is a YAML based language for defining RESTful APIs and contains all the necessary information to describe RESTful APIs. YAML is a data serialization language that is easier to read and understand than other formats like XML or JSON.

More details on RAML and its usage can be found at raml.org.

RAML API Specification

The RAML specification provides all the information necessary to describe RESTful APIs. RAML documents support all YAML features. RAML also enables documentation generator tools to extract the user documentation and translate it to visual formats such as HTML or PDF. RAML introduces the concept of resource types and traits characterizing resources and methods, thereby minimizing repetition in a RESTful API’s design.

Tip: If you are new to the YAML syntax, you will find this overview helpful.

Use Case

This article walks you through building a blogging system. The system includes the following requirements:

  • Display full list of posts.
  • Display full list of authors and the posts authored by them.
  • Display comments by readers on each post.
  • Authors can create new posts, modify or delete existing posts.
  • Readers can view and can comment on posts.
  • Authors can moderate comments.
  • Posts and authors are paginated, searchable and sortable.
  • Comments are paginated and sortable.
  • Search for a post by post title and author name.
  • Show a particular author’s post(s).
  • Show a particular reader’s comment(s).
  • View a post.

diagrams-united 

Creating the RAML File

If you are using MyEclipse or Webclipse, select File> New>Other>General>File to create a new RAML file with the name MyBlog.raml. The newly created file opens in the RAML Editor.

1. Add the Document Root

In the root section let’s add the basic information of the API, such as its title and base URI, protocols, media type, schemas, version, etc. of the api. For our example, we will implement title, baseUri and version.

title (required)—The title property is a short plain text description of the RESTful API.

baseUri (optional during development, required after implementation)—The use of the baseUri field is optional to allow describing APIs that have not yet been implemented. After the API is implemented (even a mock implementation) and can be accessed at a service endpoint, the API definition must contain a baseUri property.

version (optional)—If the RAML API definition is targeted to a specific API version, the API definition must contain a version.

2. Add Resources

This is the most fundamental element in RAML since the entire API implementation is around resources. A resource defined at the root level is called a top-level resource. A resource which is defined as a child of another resource is called a nested resource. For our example, let’s begin by creating a top-level resource named posts.

Resources have to be preceded by a forward slash (/) and end with a colon (:). Any methods and parameters nested under these top level resources belong to and act upon that resource. The post resource defined above is accessible at http://myblog.com/v1/posts. Notice that the final URL to the resource is based on the information provided in the document root section.

3. Add Nested Resources

For our blogging system, let’s add some nested resources. Nested resources are useful when you want to call out a particular subset of your resource in order to narrow it.

Similar to the root resource, nested resources can be accessed using http://myblog.com/v1/posts/authors. Even if the API has several nested resources defined, they can be easily accessed with the URL similar to the above making it very easy for the API developers and consumers to access any nested resource.

4. Add Methods

The most common HTTP methods are:

GET—Retrieve the information defined in the request URI.
PUT—Replace the addressed collection. At the object-level, create or update it.
POST—Create a new entry in the collection. This method is generally not used at the object-level.
DELETE—Delete the information defined in the request URI.

In our example, the API consumers can retrieve a post from the list of posts (GET), create a new blog post (POST), update an existing blog post (PUT), add a new comment (POST), modify existing comments (PUT), or delete posts and/or comments (DELETE).

Add the methods to the root resource (post) as follows:

5. Add URI Parameters

The root resource is made of nested resources. Resources are made of individual resources. That is, posts is made up of individual posts, authors is made up of individual authors, etc. Such individual resources can be accessed via the URI parameters. URI parameters are denoted by surrounding curly braces {} in RAML; for example, {title} for posts, {authorName} for authors, etc. Let’s add the URI parameters for our resources as follows:

To access an individual post, say post with id=1, the URL is http://myblog.com/v1/posts/1. This type of referencing is also applicable to individual nested resources.

6. Add Query Parameters

Thus far we have defined collection based resource types that are further defined by object based URI parameters. To perform additional operations like filtering on these two, we need to define query parameters. We define query parameters similar to URI parameters. Query parameters are a mixture of meta information like description, access_tokens (required by server), whether required or not. Query parameters may be defined on any number of nested resources and their methods.

Now, let’s add query parameters for all our nested resources like the ones shown in the following example. Refer to the sample file to view all nested resources that require query parameters.

7. Define Responses

Now that we have defined resources and available methods, we need to describe the responses a user can expect. Responses may include descriptions, examples, or schemas.

Responses are defined like below.

8. Define Traits

In your RAML API, there may be some behaviors, policies or characteristics that are common across different resources, for example search or pagination. Such behavior can be handled easily with traits. Traits are typically defined at the beginning of the RAML spec and can be used anywhere within the RAML. For our API, let’s define 4 traits: secured, searchable, paged and orderable.

Traits can be used across resources like below:

 


You can copy the following attachment into an existing project to get a look at the completed RAML file with all of the traits.

Congratulations, you now know how to write an API definition in RAML!

RAML/YAML Support in Eclipse

If you’re looking for RAML/YAML support in Eclipse, you can use either MyEclipse or Webclipse which installs into your existing Eclipse IDE. Here are a few screenshots covering this feature set in Webclipse.

RAMLEditor
The Editor includes syntax coloring, default formatting and syntax validation.

 

RAMLOutline
Use the Outline view for a nice overview of the file and to quickly locate errors.

 

YAMLPreferences
Easily customize the Editor to your liking.

 

Let Us Hear from You!

If you have any comments or questions, we would love to hear from you @MyEclipseIDE on twitter or via the MyEclipse forum

Related Posts

30% off sale, including Angular IDE and more! Step away from the leftovers and come take advantage of our Cyber Monday sale for Angular IDE, Webclipse, MyEclipse and more!   Thanksgiving is a great time for getting together with family, but perhaps more importantly, it’s about the SALES!  Whether it’s Buen Fin or Cyber Monday, we all love a bargain. Now is the time to get the software you alwa...
Equifax Data Breach Advisory Many of you may have heard of the Equifax data breach, possibly affecting millions of consumers. Information accessed by hackers during the incident included Social Security numbers, personal details, driver’s license numbers, and even credit card numbers.Equifax has confirmed that the breach was made possible by a vulnerability in the Apache Strut...
Realtime Server Monitoring App with Angular 4 , No... This article will show you how to build a very simple monitor that allows you to observe some OS parameters, such as free memory available. We will be using Node.js, Angular 4, and Chart.js - and all you need is Angular IDE.We will be creating two applications; the first is a Node application that will monitor the OS parameters and send them via we...
Beware of Software Scams Even though imitation might be the best form of flattery, we are Genuitec, LLC, not Genuitec, Inc. Someone is using our name and old logo to run a number of scams, including real estate transactions and software sales, with the clear intent to hide behind Genuitec’s good name. We are, however, already taking action to demand an immediate cease and ...

Posted on Jan 4th 2016