Workflow with RAML


#1

How should I take an advantage of using RAML in workflow between front end and back end?

I am working as a junior developer. I am really interested in DevOps and learn new way to make my work efficient. I read tutorial article about RAML by a accident. I searched to reason myself what advantages RAML have. And I started thinking if I can apply using RAML and make my workflow more efficient.

according to resources I found including an official web site(raml.org), advantages of using RAML seem like below

  • can make human readable and easy for documentations
  • can design your API in minutes without real coding
  • can catch those design flaws before your engineers even start coding.
  • can visually see the design
  • can test out a mock of your API

I understood that I can apply RAML in my work flow like below.
my challenge) I need to make API which interact with front end page. I need to start from making db structure(schema).
[my expectation with RAML]
step 1 : I design API with RAML
step 2 : I create documents and share with front end developer
step 3 : I even create mock server with API so that front end developer can test with example data.
step 4 : with feedback, you gradually confirm API methods and data fields.
step 5 : when you concrete structure of your API with earlier steps, you start writing real code with language such as Javascripts(Nodejs), Python(Django restframework) or others to make API.

I tried using api-workbench in atom and followed instructions. I downloaded postman and npm package ‘abao’ and tried it. I also downloaded npm package raml-server to make mock server with RAML.

it seemed that RAML 1.0 released a year ago. even after a year, it was hard to find tools and packages which support RAML 1.0. So I wondered if ecosystem for RAML is strong enough to take my time to learn RAML for better work.

In the first place, I wanted to hear many opinion from people who are more experienced and advanced in this career.

In summary, I would want to know,

  1. If i understood benefits of using RAML and a way to apply it in my work flow correctly,
  2. if ecosystem for RAML is strong enough

Thank you for reading, I am looking forward hearing various feedbacks.


#2

If you are writing code in Java or JavaScript, then RAML 1.0 should be strong enough to work with…e.g. the tooling works for those two languages. You can parse a RAML 1.0 document, though I dont know if either/both support the full RAML 1.0 capabilities… e.g. a raml file that includes libraries, etc… but I believe both work. Atom IDE uses the JS engine I believe so anything you can define in there should mean the JS library can parse it.

Outside of that, there are many RAML 0.8 users that are interested in RAML 1.0 tooling. Recently Mulesoft joined the OpenAPI initiative and put forth a tool, AMF, that will make it possible (eventually…not sure when it will work) the ability to define APIs in either RAML or Swagger, and mix between them (or transform between the two). If that works as intended, you should be able to transform a RAML 1.0 doc to an OpenAPI (Swagger 2) doc and then make use of the Swagger 2 tooling, which is pretty robust.

However, if you have the time and the thirst to do so… I would look to pick up one of the parsers and parse the RAML yourself, as it will give you more control to do exactly what you want. RAML2HTML now supports RAML1.0 as well, so you should at least be able to generate decent API documentation as well.


#3

I have nothing to add to Kevin’s comment. Thank you! :slight_smile: