RAML seems to be yet another one of the buzzwords floating around the IT space as of late. Many know that it has to do with APIs and connectivity, but they aren't positive what it is exactly or where to start. In this blog, we give an overview of RAML and its uses.
What is RAML?
RESTful API Modeling Language (better known as RAML) is a YAML-based modeling language to describe RESTful APIs. It provides a structured and clear format to describe the API. According to RAML's website, it "makes it easy to manage the whole API lifecycle."
RAML can be used in a multitude of ways: to implement interactive PAI consoles, generate documentation, describing an API you are planning to build, and more. Despite the name, RAML can describe APIs that do not follow all of the REST rules (hence why it's referred to as "practically RESTful").
RESTful APIs
RESTful (REpresentational State Transfer) APIs -- also known as RESTful web services -- are formal languages designed to provide a structured description of a RESTful web API capable of being consumed by both human and machine. They utilize HTTP requests to GET, PUT, POST, and DELETE data.
Representational State Transfer
To dive in a bit deeper, REST is a style of architecture based on a set of principles that describe how networked resources are defined and addressed. It advocates that web applications should use HTTP as it was originally envisioned. To learn more about what REST is, you can read more about it here.
RAML Tools
A benefit of RAML is the library of tools that are offered. They can range anywhere from API document generation, to converting APIs developed in other languages over to RAML (or even just from one specification to another), or a tool that will help parse, validate, and modify RAML types. Some of the tools available:
- API Console: A graphical user interface that visually exposes the API's structure and important patterns, as well as serving as interactive API documentation.
- API Notebook: A web-based JavaScript scripting workspace that enables live testing and exploring of APIs and saving API use cases as markdown gists.
- API Workbench: A full-featured integrated development environment (IDE) for designing, building, testing, documenting and sharing RESTful HTTP APIs.
- RAML Server: Exposes a full fake REST API with zero coding by writing a RAML spec.
- RAML Tools for .NET: Allows developers to easily integrate and consume APIs that expose a RAML definition, or create a new ASP.NET Web API implementation from a previously created RAML definition.
- Sandbox: Quick and easy mock RESTful API and SOAP web services. Generate from API definitions, instant deploy, collaborative build, and debugging tools for integration.
Want to learn more about the types of tools that you can find and use for RAML? Visit the Projects Library here.
Other API Modeling Languages
There is a lot of debate surrounding which language is best for developing or describing APIs. Some of the other API languages that are available:
- API Blueprint
- OpenAPI Specification (AKA Swagger)
- WADL
- YAML
In a previous blog post, we discussed the difference between RAML and Swagger as development platforms. You can find out more about their differences -- and similarities -- here.
