RAML in Mulesoft

RAML stands for RESTful API Modeling Language. RAML [4] is a YAML-based language for describing RESTful APIs. It provides all the information necessary to describe RESTful APIs. It provides a structured and clear format to describe the API. It can be used in a multitude of ways: to implement interactive API consoles, generate documentation, describe an API you are planning to build, and more.

A RAML specification consist of following sections:

1. Root

First, you'll enter some basic information in a text editor. You can save your API's RAML definition as a text file with a recommended extension “.raml”.

Everything you enter in at the root (or top) of the spec applies to the rest of the API. This is going to come in very handy later as you discover patterns in how you build your API.

2. Security

Security is also defined at the root level of the .raml file. So let's add our HTTP basic security scheme definition

3. Resources

It's important to consider how your API consumers will use your API. It controls the consumption of the API. For example, consider the functionality of the mytrain customer system API. In this we want user to register for the service and allow them to view only their personal and subscription information. Then the resources used will be user, userId, and subscription as shown in the figure below

In RAML, all the resources begin with a slash (/). Any methods and parameters nested under these top level resources belong to and act upon that resource.

4. Methods

You can add as many methods as you like to each resource, at any level. However, each HTTP method can only be used once per resource. The most common HTTP methods used 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.

▪ DELETE - Delete the information defined in the request URI.

Example:

Method=POST; URL=/api/v1/foos

Method=PUT; URL=/api/foos/{id}

Method=DELETE; URL=/api/v1/foos/{id}

Method=GET; URL=/api/v1/foos?name={name}&ownerName={ownerName}

5. URI Parameter

URI is a Unique Resource Identifier as the name suggests, it is used to get a unique resource. The parameter which is part of the URL that is passed to get the unique resource is the URI parameter.

Example:

/api/foos/{id}

/user/123: Gets a user information whose id is 123

6. Query Parameter

Query parameters are used to filter the resources. The query parameters are passed at the end of the URL after a question mark to sort, filter or paginate the resource.

Example:

/user?status=active: Get the users whose accounts are in active state

/api/v1/foos?name={name}&ownerName={ownerName}

7. Request

We define the request bodies that correspond to each POST and PUT request.

8. Response

Responses MUST be a map of one or more HTTP status codes, and each response may include descriptions, examples, or schemas

When you’re designing an API, it’s important to think about how to build your API for the long-term and make sure there aren’t bad design elements like glitches or inconsistencies. RAML is recommended as a good spec building tool as it offers the most support for Spec-Driven Development, and it also allows you incorporate API design best practices, enables you to reuse code, and lets you take advantage of design patterns to ensure consistency in your API.

9.API Fragments

● API fragments are reusable components of RAML to make the design and build of a reusable API even quicker and easier.

● Reusable APIs and API fragments are a critical factor in closing the IT delivery gap that arises when there are too many IT projects that need to be delivered with too few IT resources. Instead of starting every project from scratch, you can reuse fragments and APIs to accelerate project delivery.

● Let’s imagine you were building a customer API. You’ll notice that some of the snippets or “fragments” of the API spec have a lot of potential for reuse. This can be a security scheme or a data type. For example, a customer data type can consist of first name, last name, and address. Most likely, the way you describe a customer stays consistent across your APIs, which makes this data type, or fragment, reusable. If you build a library of these fragments, you then have many assets for reuse that can accelerate the speed of building your API spec

● API fragments can be divided into: datatypes, traits, libraries, examples, annotations, security schemes etc.

● This can be seen by going to the design centre → create fragments → and go to the drop down section to see the list of available traits.

10. Data Type

Data Types, a concise and versatile way to describe and validate data inside your API definition.

Some of the data types available in RAML are string, integer, data-time etc.

You can define a type at the beginning of your RAML file, and you can later reference that same type to describe the body of as many API requests or responses as you need

In any scenarios dataype files can hold only a single datatype of a specific resource.

Alternatively these data types can also be defined in a folder and referred in the main RAML file as shown in the below images

11.Traits

● Traits are like functions and are used to define common attributes for HTTP methods (GET, PUT, POST, PATCH, DELETE, etc) such as whether or not they are filterable, searchable, or pageable.

● Traits can be declared in the same RAML file or you can create different files for creating the traits

● some of the practical snapshots are given below:

12.Library:

Libraries provide the ability to bring in pre-defined sets of data-types, resourceTypes, traits, security schemas, and reusable assets - all in a namespaced environment

When we want to define more than one datatype in a single file so that easy data retrieval and editing can be done. In such scenarios we can go for Libraries.

And as the definition says, it's not only used for datatypes for all other traits like examples, traits etc but widely used for datatypes.

Some practical examples:

13.Example

Example fragment is used to define the example response of some operations we are doing in the RAML spec.

Example fragment is used to define the NamedExample.

Some of the practical examples are given below:

All these fragments can either be defined specific to our RAML project and used extensively or defined as separate fragments and then published to exchange so that it adheres to the principle of reusability.

We can write separate fragments like examples, traits, datatypes etc. and publish them to exchange so that they could be reused by other people too. The way to do this is clearly mentioned in the POC attached with this documentation work.