Designing and Documenting Your APIs Using RAML

Most of the projects in which we participate in my work designing and implementing APIs require access to mobile applications and web apps. This design requires defining an authentication system (e.g. one based on tokens such as JWT) and each of the endpoints that will be accessible. In this definition of endpoints we must decide on input fields and outputs for each.

To design a good API, you must use HTTP verbs properly using REST, but you also need to implement an intuitive design, good documentation, and a faithful representation of implementation. A part of that implementation is good, it is very important that the documentation associated with it is complete and is current by 100% having controlled the expected behavior for each request. In my opinion, keeping this commitment is usually quite complicated, but using the right tools can simplify the process and benefit the development team, and future developers can instruct the software development better.

After several months considering this, we decided to use RAML to document and design our APIs, although we were considering other solutions like Swagger. Let's detail what RAML is and how it works.

What Is RAML and Why Use It in Our APIs?

RAML is an acronym for "Restful API Modeling Language" and is a modeling language to define REST APIs with a fairly simple and easily understandable syntax for both humans and software systems. This language allows you to define resources, methods, parameters, responses, media types, and other basic HTTP components. Basically it is a non-proprietary and fully independent specification based on YAML and JSON. In other words, it allows us to write the specification of the APIs following a standard.

The great advantage of implementing a RAML API is that you focus completely on the "contract" that provides the endpoint; this allows you to start generating the documentation, which, once ready, provides different generators to generate the basic service "scaffolding" and even services that return answers, simulated to start our testing.

This methodology favors the testing process, providing us with the perfect environment to use TDD. Basically, we define the API, write tests to consume this API and started building the actual implementation and necessary tests to validate both the specification as described.

How to Write RAML

You can write just a normal file with the extension .raml and process it with different tools. Personally, we use an official tool called API MuleSoft Designer (https://github.com/mulesoft/api-designer). This tool is an editor built with AngularJS and you can install through NPM on your computer.

npm install -g api-designer

Some Useful Tools

• JS RAML Parser: https://github.com/raml-org/raml-js-parser

• RAML Java parser: https://github.com/raml-org/raml-java-parser

• RAML SOAPUI Plugin: https://github.com/SmartBear/soapui-raml-plugin

I recommend watching the official tutorial to start creating your files RAML.