Restful API Modeling Language | Sovereign Solutions

Restful API Modeling Language

API Documentation

API documentation is essentially the reference manual for an API – It tells API consumers how to use the API. API documentation is meant for humans, usually developers, to read and understand. Providing documentation that is well-designed, comprehensive, and easy to follow is crucial when it comes to ensuring developers have a great experience with the API. And a great developer experience (DX) means a better chance for API success.

There are many tools available for generating and maintaining API documentation. Many of these tools can automatically generate both static and interactive API documentation from an API definition file.

It should provide an example of every call, every parameter, and responses for each call. It should include code samples for commonly used languages such as Java, JavaScript, PHP, and Python.

API Specification

API specification is a term that is often used interchangeably with API definition. While these terms have many similarities, they are different entities. An API specification provides a broad understanding of how an API behaves and how the API links with other APIs. It explains how the API functions and the results to expect when using the API. A good example of an API specification is the open API Specification.

In the document, there are many API objects, values and parameters, how the objects are called, and what each object does. We also see the relationships between the objects and how each object can be used.

For example, if you look at the Request body object section, you’ll find information as to what this object does, the descriptions and types for its fixed fields, and request body examples. You will see how the Request Body Object is supposed to function and what to expect when using this function. An API specification is also an indication of how the API is designed and the data types the API supports.

OpenAPI (formerly the Swagger specification) is one of several API specification languages. There’s also RAML and API Blueprint. It should be noted that there is momentum towards these API specification languages converging into one API specification language, OpenAPI.

API Definition

An API definition is similar to an API specification in that it provides an understanding of how an API is organized and how the API functions. An API definition provides information about how the API functions, how it links with other APIs, and the expected results in a machine-readable format. It focuses on defining the API and outlining the structure of the API.

An API definition is often used as a baseline for automated tools. API definitions can be used to generate API documentation, code samples, and SDKs automatically. A few examples of tools that generate API documentation (static and interactive) from an API definition file are SwaggerHub and Swagger Inspector.

API definitions can also be imported into a mock server for virtual API testing. Among the many tools for mock server and API testing that allow import of an API definition file are SoapUI and SwaggerHub.

An API definition is important in that it can be used to power automated tools that can ensure the success of your API like interactive documentation and SDKs.


RESTful API Modeling Language (RAML) is a language intended to describe RESTful APIs.  RAML is written in the YAML human-readable data serialization language.  It’s very simple and readable, it allows us to easily design, mock, test and document APIs.

The RAML effort was first proposed in 2013 and garnered support from technology leaders like MuleSoft, AngularJS, Intuit, Box, PayPal, Programmable Web and API Web Science, Kin Lane, SOA Software, and Cisco. The goal of RAML is to provide all the necessary information to describe RESTful APIs, thus providing a simpler way to design APIs.


Clear: The structure of the API should be manifest. Patterns are brought to the forefront; its data and interaction models are front and center.

Correct: An API spec is a contract: whatever is captured must correctly describe the behavior of the API

Precise: Can a client be generated from the spec that’s as faithful to the API as it is reasonable? Do the implementers know what they’re required to deliver?

Consistent: RAML has strong support for capturing patterns. It encourages reuse, enables discovery and pattern-sharing, and aims for merit-based emergence of best practices.

Readable & writable: Optimizes both creating and reading specs by impatient, smart humans.

Natural & intuitive: It is as close as possible to the mental model one has for the API, like what you’d type out in an email to a colleague or friend you were helping design or consume the API.

A sample RAML file of the Notes Example API (courtesy of MuleSoft) is shown below.

#%RAML 0.8

title: Notes Example API

version: v2

mediaType: application/json


– title: Overview

content: This is an example of a simple API for a “notes” service


description: A collection of notes


description: List all notes, optionally filtered by a query string



description: An optional search query to filter the results

example: shopping




example: |

[ { “id”: 1, “title”: “Buy some milk”, “status”: “done” },

{ “id”: 2, “title”: “Return sweater”, “status”: “overdue”, “dueInDays”: -2 },

{ “id”: 3, “title”: “Renew license”, “status”: “not done”, “dueInDays”: 1 },

{ “id”: 4, “title”: “Join gym”, “status”: “not done”, “dueInDays”: 3 } ]


description: Create a new note in the collection


example: |

{ “title”: “Return sweater”, “dueInDays”: -2 }



description: You can specify request headers like this

enum: [ accounting, payroll, finance ]

required: false # require it by changing this to true

example: accounting





description: You can describe response headers like this

example: RAML


example: |


“id”: 2,

“title”: “Return sweater”,

“status”: “overdue”,

“dueInDays”: -2



description: A specific note, identified by its id



description: The `id` of the specific note

type: number

example: 2


description: Retrieve the specified note




example: |


“id”: 2,

“title”: “Return sweater”,

“status”: “overdue”,

“dueInDays”: -2

RAML itself provides a full API design lifecycle, broken into five categories.


By use of the easy-to-read YAML format, API design can become more visual than prior API development approaches. Utilizing a dedicated RAML tool (API Workbench, API Designer) or IDE plug-in (Sublime, Visual Studio) facilitates faster development, eliminating code duplication and providing functionality to prototype and perfect APIs being developed.

With the building blocks in place for an API inside the RAML file, mock data can be added to allow for prototyping and testing before any actual program code is written. As a result, designers can sit with stakeholders and product owners to validate the API early in the development process.


With the design of the RAML file in place, the actual programming of the API logic can begin. At this point, the RAML file becomes a specification and popular languages like NodeJS, Java, .NET, Mule, and IOT Noble can simplify the build process.

Below is an example based in Java and the RAML for JAX-RS framework:


public interface NotesExampleResource




Response createNote(Note note, @Context UriInfo




Notes getNotes(@QueryParam(“q”) String query,

@Context UriInfo uriInfo);



Using the RAML for JAX-RS framework, it is possible for Java interfaces to generate a RAML file, as well, which provides another option for leveraging the RAML specification. With the design and build phases in place, the next logical step in the API Development Lifecycle is the testing stage. These unit tests are critical to making sure that the API being developed maintains any backward compatibility while also meeting all the current requirements.

Tools like Abao, Vigia, and Postman allow RAML specifications to be imported, leading to setup scripts and tests being created to validate the API. Additionally, testing services (like API Fortress, API Science, and SmartBear) provide assistance toward testing latency, responses, payloads, and errors.


API documentation has been a challenge, with tools like Swagger and Miredot often falling short at providing complete information and leading us to rely on developers to specify cryptic annotations and language-specific documentation like JavaDocs.

With the RAML specification keeping documentation as a core priority, the documentation is kept in sync with the code itself. This refreshing benefit is due to the fact that the RAML specification serves as an interface (or contract) for the API itself – in sync with the underlying business logic providing results for the service.

Tools like API Console, RAML to HTML, and RAML2HTML for PHP provide quick and easy ways to expose standardized documentation – which can be kept private on a corporate intranet or available for public consumption.


With all the building blocks in place in the API Development Lifecycle, the final segment focuses on sharing the API. The RAML specification introduces several ways in which APIs can be integrated.

SDK Generation: Languages like Java, .NET, PHP, Ruby, NodeJS, iOS, Windows, and Go provide push-button functionality to build Software Development Kits (SDKs) automatically using the RAML file.

Third Party Tooling: Oracle and MuleSoft include RAML functionality into their toolsets to provide the ability to connect to any API utilizing RAML just by pasting in the specification.

API Notebook: Provides an environment for developers to test APIs, manipulate results from API calls, and connect to multiple APIs using the JavaScript language.

OpenAPI (Swagger) Vs. RAML

Swagger—recently renamed to Open API** or OAS—is a type of framework that was designed to describe, produce, visualize, and consume RESTful web services. Referred to “language-agnostic,” it has been developed to be read using a common language. produced a perfect example that can be used to help understand exactly what Swagger is:

Think of it as a blueprint for a house. You can use whatever building materials you like, but you can’t step outside the parameters of the blueprint.

Swagger’s popularity stems from its simplicity. From its concise documentation to its to its ease of readability for machines and humans alike, Swagger is a framework that has been made very easy to utilize.

OpenAPI as well as RAML have very much in common.

Projects relying on the extensive language support and tool integrations will tend to OpenAPI. But if the language support is not crucial as implementations are foremost done in standard languages such as Java, RAML is an equivalent option.

OpenAPI and RAML both have a large community and are backed by market leaders, so you will never be wrong choosing one of them for API documentation.

Swagger’s best features are its strong documentation and compatibility with lesser used languages. It provides a fast setup and a large support community. The big takeaway for Swagger is that it is designed as a bottom-up specification. Swagger specifies the behavior which affects the API to create more complex, interlocking systems.

RAML excels at supporting the entire API’s lifecycle. It provides a balance between developer tooling and technical writers without taking away from one or the other. It also is the fastest framework to ramp up your project. The main difference between the two is that RAML is a top-down specification, meaning it breaks down the system and explains the behavior of the various sub-components.

Talk to our experts now to learn how Sovereign Solutions can help your organization meet its business objectives

*This content is being provided for informational and educational purposes, and should not be regarded as a specific recommendation for your situation.