API Management Best Practices: Using RAML & the Anypoint Design Center

RESTful API Modelling Language (RAML) is a YAML based API language to describe RESTful APIs. RAML provides a structure for developers to start their development process and helps stakeholders understand what an API does beforehand. RAML specification promotes the standardisation and reusability of an API. 

What is API Specification?

API Specification is the blueprint of an API, which communicates how an API behaves. It provides all the necessary information needed to describe an API, such as:

• What is the expected request?
• What is the response?
• Data type library.
• Mandatory/non-mandatory parameters.

Where and how to start designing a RAML?

RAML can be developed using any of the following:

1. Notepad.
2. Anypoint Studio.
3. Design Center.

When working with MuleSofts' Anypoint Studio, we recommended designing a RAML in the design centre before importing it into the Anypoint Studio for flow implementation.

How to design in Design Center?

The prerequisite is to create an account in https://anypoint.mulesoft.com/ to get access to the Anypoint Design Center, and follow these steps:

1. Go to the Design Center
2. Click Create New 
3. New API spec
4. <Provide the API Title> 
5. Create API Spec

Initial RAML design(without best practice):

Can the development be started without an API Specification?

Yes, it can be, but we recommended starting with the API Specification as a best practice.

Key of RAML?

Resource: A unique name to identify a resource and the name should specify the usage of an API.

Method: Method of a resource to specify the operation.

Request: This contains the Request body detail and its type.

Response: This contains the Response body detail.

HTTP Status: This is the standard response code to identify the response status.

Traits and Library: A readable and reusable library.

HTTP verbs and Methods

GET (Idempotent): To obtain data.

PUT (Idempotent): To update the entire data. It can be used for both creation and updates.

POST (Not Idempotent): To create data based on the provided request.

PATCH (Not Idempotent): To update a partial instance of data.

DELETE (Idempotent): To delete data.

HEAD (Idempotent): Returns the metadata of an object for a GET response.

OPTIONS (Idempotent): Used to send the request for checking with the server for sending the cross-domain request.

What are URI and Query Parameters (Params)?

A URI Param is used to identify a specific resource. It's a variable element passed as a resource.
The Query param filters the response data, passed in the URL as a key-value form.

Points to check for RAML design

• The proper naming convention to be followed while designing RAML.
• RAML file name should be in lower case.
• Resource name, traits, libraries and example file name should be in camel case.
• Resource name should be a noun and recommended to have nesting.
• Specify the version of the RAML file.
• Recommended to write a description of the resource functionality in RAML
• Fragments to be followed based on resource functionality.
• ResourceTypes, Traits, and SecuritySchema should be created in fragments to serve the reusability in RAML.
• Use traits to define common method properties such as headers, query params and error-response.
• Separate the traits and types file from the base RAML file, and externalise them in a separate file.
• RAML should have low coupling and high cohesion.
• Define standard error message schema with the error code and sample example.
• Use JSON as a data format.
• Specify the data type library and sample example file for the Request and Response body.
• In a large Response, define the offsets and limits to the pagination of the Response and avoid performance issues such as response timeout.

Sample RAML with best practices:

The snippet below shows the base RAML file, including Resource fragments, type library, traits, and the RAML file hierarchy.

RAML fragment sample

The following snippet shows the resource fragment, which includes the API specification of the resource.

Example JSON and error response JSON

This snippet shows the sample example and error response example hierarchy.

RAML fragment with nested resource example

The below snippet shows the nested resource hierarchy, reusability of type and examples, and query parameters as traits to reuse.

Type library reuse example

The snippet shows the reuse of the type library file.

How to Import RAML from the Design Center to Anypoint Studio?

The first step is to configure the Anypoint Platform with Anypoint Studio by the below steps:

1. <Right click on the project name> 
2. Anypoint Platform 
3. Configure Credentials 
4. <Under Authentication> 
5. Add 
6. (Provide credentials to connect with the Anypoint platform)

Note: Configuration can also be set from Preferences, steps as follows:

1. Windows 
2. Preferences
3. <Expand Anypoint Studio> 
4. Authentication  
5. Add 
6. (Provide credentials to connect with the Anypoint Platform)

Once the configuration is set, we can download the RAML from the Design centre by following the below steps:

1. <Right click on the project where RAML needs to import> 
2. Anypoint Platform 
3. Download RAML from the design centre 
4. For the configuration set, it will list all the RAMLs available in the Design Center.

5. Select the RAML to be imported
6. Click OK

The RAML will be imported under the src/main/resources package, and an initial XML file (having the same name as the RAML) with APIkit router, error handler and other source flows are created.

These flows can be further implemented based on the requirement.

How to access the API

By building the .jar file of the API and deploying it in the Runtime Manager of Anypoint Platform, this API can be accessed by the other APIs at the enterprise level.

For the local testing, we can deploy the API locally and access it from the Postman by triggering the listener configuration set and the path.

To deploy locally: 

1. Run As 
2. Run configurations 
3. <Select the Mule Project to launch> Apply 
4. Run

The deployment status can be checked in the Console. Once deployed to the local system, we can test the API by any tool, such as Postman.

In the below snapshot, 8082 is the port where our API is listening. Test/* is the basepath configured, and /account is the source endpoint with query parameter customerId.

If you would like to find out more about how we can help you leverage the RAML and MuleSoft, give us a call or email us at salesforce@coforge.com.