Am I missing something?


#1

I don’t get RAML (or similar projects).

Correct me if I am wrong, but RAML is just a fancy YML to describe the requests and responses of my API… right?

However, the code to implement such a blueprint, is created, manually. And if I need to “test/confirm/validate” that my code conforms to my RAML file, is done… manually?

The abao project doesn’t work on RAML 1.0 and so… I don’t get why I would need a RAML file other than to replace my documentation on a google doc?

How do I ensure my code, conforms to my RAML?
How do I test,validate the responses? How do I at least get some sort of coverage report against my RAML?

Doing this on Express.

Please help.


#2

You are not entirely incorrect… however… the goal of something like RAML or Swagger is to provide a way to descriptively define an API, that hopefully tool developers will then build tools that parse that description into useful end results, such as generated code that can implement the API endpoints, or automated tests that can run against an implementation (or mock) to test that the API works as described.

To me, and many others, the real benefit, besides using these tools, is the ability to define every aspect of the API in one file (or group of related files), as a single source of truth, that then spawns/generates all the other facets that enable rapid development cycles that are easier to boot. Now, part of the problem with what I am saying is that there is no one tool vendor writing a complete set of tools that does everything. Thus, we are left having to pick the tools we want to use, and hope they play nice together, to give us that total package.

So in theory, if all the tools were available, what you are asking is possible. To some extent, it is now. You just have to add some manual intervention to piece together the steps. Ultimately, someone may come along one day and offer a complete set of tools that handles documentation generation, code generation, test generation, etc. RAML 1.0 specifically adds a feature that would require every tool to agree to the same thing…e.g. annotations. As an example, there is no deprecation tag to use in RAML to specify an API is to be deprecated. It is easy, however, to add an annotation for that purpose. The problem is, every tool you want to use, from documentation, to code generation would need to know about that custom annotation, the exact name, its purpose, all agree to it, and then implement their parsing of it for each purpose. e.g. documentation would add some note/disclaimer about the API being deprecated, code generation would add necessary code details to allow it to be shown as deprecated, tests might offer a different route for deprecated API endpoints or no longer test them… something like that.

Anyway, for what it is worth, I have faith that the right set of tools will present sooner than later, especially for RAML 1.0, and most of them are usually open source, so it it not always difficult to contribute to them if needed. For me, just the definition and documentation alone is a big win, and code generation and tests is a nice add.


#3

I can only echo what @Kevin_Duffey already said. There is a lot going on in the community to provide what you are looking for. For example, the people that using abao took over the project and are continuing to implement the RAML 1.0 support. They have a huge plan for it, but it will take some time for some since everyone is doing that in their spare time. Which is important to bear in mind and is what Kevin already said as well.

With RAML you actually get more than just a documentation within a Google Doc. RAML is based on two simple principles:

  1. Make it as simple as possible to write and read APIs
  2. Promote reusability and consistency

The second is a key differentiator to the Google Doc approach. Creating small sets of reusable components makes modeling APIs more succinct and consistent across multiple API descriptions. Define how “paging” works and share it within your organization so that they can easily reuse your best practices. Avoid defining it over and over again.

The specification gives you a lot of advantages compared to more documentation-only based approaches like Google Docs.

Anyways, your are right that the tooling part is also important. There are people creating tools at the moment driven by their passion for growing the RAML ecosystem, all in their spare time. I have seen a lot happen in the last few months and I am certainly looking forward to see what else people will contribute in the future.


#4

Thank you all fo the replies.

I think the most significant gap right now, is being able to at least
assert the routes are created and they are set to return the correct status
codes. Not a running test, but at least just a high-level verification of
conformity with the RAML. The rest of the reasons why to use RAML are very
valid.


#5

I think that’s what Abao is about. Not sure if testing the correct status codes is something easy though :slight_smile: