RAML 1.0: This is Why They Teach History in School

Fifteen years ago we had more hair, no mortgage, and WSDL.

At that time we were calling them “web services” and XML was the format, while WSDL suddenly became an extraordinary tool for allowing our web services to be easily consumed by remote applications all over the Internet. The great thing about WSDL was that it described endpoints, interactions, and data, in a way a machine could handle the communication without the developer having to know much about the underlying web service.

WSDL, SOAP, and XML were great… and tedious. They were protocols and languages machines liked much more than humans.

Soon after, JSON based web services became THE thing. What really made the difference compared to XML is that JSON represented various data types and was much more readable to humans.

The human readable part is what made the difference. Web services could be created without involving killer technologies, complicated wrappers, and dreadful descriptors. Easy to be written and write the code to consume them, requiring just a peak at the payload.

This new approach is a vital part of the modern Internet, with its startup melting pot and mobile app proliferation.

Setting standards, RFCs and expectations are important, but the key was providing developers a human readable, easy to be parsed format. That was the tipping point that led to what we have today.

From this came the new generation of descriptors – RAML and Swagger. Exposing endpoints with a bunch of options that can produce a bunch of data is a start, but the key is to empower your partners with a powerful, extended API they can rely on. This is where APIs switch from being a utility to being a key component of a company strategy.

These new descriptors are built with the lessons learned from the WSDL days. They have always been human and machine readable. They allow developers to understand what to expect, and machines to learn facts about an API and react accordingly.

Welcome RAML 1.0

We met RAML one year ago and immediately recognized it was the kind of descriptor that met our needs. It allowed us to determine endpoints, choose how to perform requests with parameters and headers, and have a certain idea of the payload behavior both in XML and JSON. But one thing of the puzzle was still missing. So when the RAML work group showed us the next version we had high expectations. Our CTO was wowed during the call.

There are a number of great features including – a more rational reorganization of the descriptor, documentation generation, and the API Workbench – but what really shocked was how RAML is finally able to describe both the data and logical entities. This is now just an API descriptor, but a modeling language. It:

  • Improves human readability. Developers can actually read what to expect in a way that does not represent data, but information.
  • Empowers effective code generation. By describing entities, stub generation tools can also generate complex classes and objects.

The team worked on new libraries and utilities that effectively parse RAML, and also allows the creation of complete client libraries for a RAML described API. Abstracting almost completely from the underlying technology, in the language of your choice.


Egoistically speaking, for API Fortress, empowering anyone to test APIs is great for us. The more our engine can learn autonomously, the better a QA analyst can concentrate on the sneakier parts of an API program. Any tool that can ease technical headaches, and free creative people to spend their time solving unique issues, is a great step forward.

Our team is fully committed to using anything that makes life easier for our users. RAML does this, and we are excited to improve our platform with all that it offers. RAML is a great step towards a standard. Once we can find a standard an API tipping point will occur again. Where we can all work on the creative, and spend less cycles on the technicalities.