raml

RAML (RESTful API Modeling Language) is a YAML-based language for describing RESTful APIs. It enables developers to model endpoints, resources, methods, parameters, request and response bodies, and security schemes in a machine- and human-readable form. RAML supports a design-first approach, allowing API designers to specify contracts before implementation.

Key features include reusable components such as resource types, traits, and data types, as well as libraries to share definitions across APIs. The syntax is YAML, commonly used for API descriptors. RAML documents begin with an API title, version, and base URI, followed by a tree of resources that maps to URL paths. It supports datatype declarations and shape-based validation, providing modularity through libraries and a composition model. Annotations extend metadata. Tooling includes API Designer, RAML parsers, documentation generators, and code generators that can produce API docs, client SDKs, server stubs, and mocks.

RAML was developed by MuleSoft and released to the broader community as part of an open ecosystem. It remains a widely used option for API design and documentation, competing with OpenAPI. RAML 1.0, published in 2015, introduced significant improvements in modularity and the type system.

In practice, teams use RAML to define an API contract early, enabling downstream tooling to generate documentation, mocks, client libraries, and server scaffolds, and to simplify API governance within an enterprise.