APIs are complex and can be developmentally costly and difficult to document due to frequent updates. RAML offers a simplified approach to addressing the common challenges and inefficiencies associated with API development, design, documentation and management. Using RAML code, developers can create specifications that describe how an API works and deploy them to manage API lifecycles.
Consider RAML’s strengths, limitations and best practices for implementation before adding RAML to your toolkit.
What is RAML?
The RESTful API Modeling Language, or RAML, is an open source development language for describing RESTful or practically RESTful APIs. It was created in 2013 by an array of companies, including MuleSoft, an IT automation and integration vendor, that played a major role in its development. In 2018, Salesforce acquired MuleSoft, which now owns the RAML trademark.
RAML is based on YAML — a recursive acronym that stands for YAML Ain’t Markup Language — a data serialization language often used for writing configuration files to support workloads like those deployed on Kubernetes. If you know YAML, the RAML code will look familiar. However, the major difference between RAML and YAML is that YAML can describe numerous configurations, and RAML is designed only to describe APIs.
Despite its name, RAML does not support every REST-based API. True RESTful APIs, also referred to as REST APIs or web APIs, are based on the architectural style of representational state transfer, or REST, and must adhere to six constraints — uniform interface (UI), client-server model, stateless operations, RESTful resource caching, layered system model and code on demand. RAML offers flexibility in describing APIs that can adhere to most, but not all, of REST’s architectural principles.
RAML’s accessibility as a specification language lies not only in its flexibility to describe APIs but also in the consistency of its descriptions. RAML promotes standardization through its provided structure and allows developers to generate code that summarizes an API’s functionality in a highly readable format that’s easy for both machines and humans to interpret.
What is RAML used for?
RAML enables developers and architects to do the following:
Describe how an API is intended to work when designing it.
Document how an API works once it’s developed.
Manage changes to an API over time by tracking changes to the RAML code that describes it.
RAML was introduced in part to mitigate widespread inconsistencies and inefficiencies when describing how APIs work because APIs can function in a variety of ways. For example, they can accept many types of queries, use different MIME types to format data and generate varying response codes. As a result of this variability, an API description format that works for one API might not work for another.
The inconsistent nature of APIs means that developers sometimes resort to prosaic documentation to explain how APIs function. In other words, they use natural language instead of computer code to document their APIs. This type of API documentation takes time, and it’s difficult to process such documentation programmatically because it’s not structured consistently.
RAML addresses these challenges by anticipating every attribute that could exist in a REST API and providing a way of defining each attribute using code. RAML makes it possible to describe APIs consistently without having to write traditional documentation.
The limitations of RAML
RAML is a powerful tool for developers who need to describe and manage APIs, but it has some shortcomings:
RAML does not explicitly support APIs driven by Hypermedia as the Engine of Application State (HATEOAS). Some developers have innovated ways of making RAML HATEOAS-friendly, but description issues can still arise.
RAML’s ability to reuse code is limited, and it’s only compatible with certain API management tools. Depending on the needs of the user, some developers prefer other tools for describing APIs, like Swagger.
Best practices for getting the most from RAML
Review these tips and best practices for maximizing RAML’s description capabilities:
Be consistent. Although RAML standardizes descriptions for almost any REST API, the user must decide how to structure the code and name files. Consistency and organization are key components for development and maintenance.
Make the code complete. RAML doesn’t have a way of knowing whether an API description is missing important information, such as error message schema. Be sure descriptions are comprehensive and include all relevant information about how the API works.
Version-control the code. Trace evolutions of the API’s functionality by automatically tracking changes to the RAML specifications over time.
Validate the code. As with any code, RAML specifications could contain errors like missing brackets or quotes that lead to misinterpretation. Because RAML is a YAML-based language, a YAML code validation tool can detect errors.
Chris Tozzi is a freelance writer, research adviser, and professor of IT and society who has previously worked as a journalist and Linux systems administrator.