In my last post I talked about what annoys me about Swagger. This evening, I took the time to see whether there are any good alternatives out there. As it seems, there are a lot of them. Two of them I found especially worth looking at: API BluePrint and RAML. This article is about RAML, but I’ll definitely post another one on API BluePrint.
RAML is a specification format that looks like a YAML file. It describes how a REST webservice should look like and how it should behave with regards to return values. In short, it’s what WSDL is to SOAP webservices. RAML specifications are not hard to write and is a top-down approach to REST webservices, unlike Swagger, which is a bottom-up tool mainly aimed towards documentation. You’ll write the RAML specification before writing the code.