Is RAML still used?

What is the difference between RAML and swagger?

RAML stands for RAML API Description Language and is an open standard to describe APIs in a language agnostic way.

It was created by Apigee and was formally adopted by the OpenAPI Initiative. Swagger is a commonly used open standard to describe APIs that was created by Swagger Inc. You can think of RAML as XML for APIs and swagger as JSON for APIs.

RAML is a formal specification for describing APIs and has been gaining adoption among a lot of platforms including Microsoft's Azure API Management, IBM's API Gateway, Google's Cloud Endpoints, and SAP's Rapid API Management. Since RAML is a well-defined format you can validate your API descriptions using the RAML validator and generate code using the RAML generator.

Swagger is a widely used open standard for describing APIs and it describes the API by including a separate JSON document describing the structure of the API. It was created by the Google team and they later open sourced it. Some of the popular platforms that support swagger are Microsoft's Azure API Management, IBM's API Gateway, Google's Cloud Endpoints, Amazon's API Gateway, and SAP's Rapid API Management. It's not a formal specification so you cannot validate your API descriptions using the Swagger validator. But you can generate code from it using the Swagger generator.

Swagger tends to be more popular for API descriptions for smaller projects. The most important difference between them is that swagger does not require you to create an API definition file which is more of a burden than RAML. RAML is ideal for APIs that have multiple resources, but in case of small projects swagger is ideal. You can use both together and there's no need to prefer one over the other.

RAML stands for "Representational State Transfer" and is an open standard that describes APIs in a language agnostic way. The goal of RAML is to allow for API description with minimal effort (similar to XML for other types of non-human-readable content). Swagger is a collection of web technologies that allow for human-readable API descriptions. Swagger is typically used for APIs that are hosted on the same server as the API itself, such as a REST API. RAML is typically used for APIs that are hosted in a cloud-based system such as an API management platform.

What does RAML do?

RAML is a set of definitions used by developers and/or consumers of RESTful services to provide unambiguous descriptions of services.

The RAML language is based on and designed to fit with RIMES 1.0 (RESTful Internet Messaging Model and Specification), a protocol intended to provide a standard framework for the exchange of messages for the purpose of web services interoperability. A typical use case might be to send a message for logging a certain error. In this case it is possible to use the RAML specification to define the message (eg the body of the message, ie the parameter). The other side of the RESTful service can then consume this information (ie send the body), using a protocol like HTTP POST to do so. One problem with RESTful services, however, is that each message is typically created on the fly and has no context associated with it, making it hard to validate or understand the intended usage, as there is no context to check the meaning behind a given URI. A standard way to solve this problem would be to pass the message as an attached object to the URI which the service provides, allowing the caller (consumers) to pass it around and have it validated, thus providing a context for the message. This was what was originally envisioned by Roy Fielding, who proposed REST as an architectural style for web services, which he later published in a document he gave an Apache Software Foundation trademark in 2024. While REST has proven popular for its simplicity and scalability, there have been criticisms that it is difficult to scale over the internet due to state management. Many of these issues were addressed in another document in 2024, namely the RESTful Web Services Architecture 1.0 from which the RAML specifications were derived. Unfortunately, this specification was only released on Github, and thus does not see the light of day in the open source world. What has led me to write this document was a need to define a method for providing context to RESTful services and how they could then be consumed in an object oriented way, along with what I want to achieve by using such a method. The biggest difference with respect to existing standards is that while the W3C Web Applications Framework, ie W3C Web App Framework (WEBF) 1.

Is RAML still used?

I'm about to start a new project using .

Net MVC and the RAML spec, I know the purpose of RAML is to expose REST services in a formal way but is it still used nowadays? Is it still used for any purpose or is it just for legacy purposes? RAML is used as a standard by which to describe REST API's (Web API's). It is being used because it's good practice to have a standard to describe your API.

There are some other things that you can do with RAML that don't have a direct equivalent in the WADL format. For example, you can annotate the types of your API.

I'd like to add to what Robert said. RAML is an acronym for Routing And Manifestation Language. In reality, it's just a specification for describing RESTful services, but it's very useful as a mechanism for communicating with API consumers.

For example, it lets you describe the resources available on a particular URI, the query parameters available on that URI, and the structure of the data returned by that URI. This is particularly useful when you're building an API that can be consumed by external systems, such as mobile apps or desktop apps. If you were to generate a WADL (Web Application Description Language) for your API, you'd get a bunch of XML, which might be confusing for consumers. RAML provides a much more friendly format for communicating with clients.

There are a few cases where the RAML API specification is used: To expose an API (I think it is more commonly used to expose web APIs). As a documentation format. As a way to generate code for an API. The last one is the most common use case and I think it is the one you are referring to. In the last case, the RAML specification can be used to generate a simple and nice API documentation, see the API Generator on the RAML website. There are a few other projects around, like RAMLit, that can be used for generating code for APIs and also generating documentation.