RAML server frameworks: how to roundtrip


#1

As people start to implement server frameworks for RAML, it’s important to consider round-tripping support: if you define your RAML contract, then go implement it and perhaps make changes as you do so, then reflect those changes back into the RAML. How would you like to see round-tripping done?


#2

In addition, as RAML is the representation of an API, is important to consider the case that you modify some part of the API contract dinamically (with an API Manager tool for example). Should the RAML be also modified? I think the answer is yes, because the RAML (and the displaying tools associated, for example the console) needs to be updated and reflect the changes.


#3

I personally believe that any mismatch between the RAML specification and the actual implementation should fail immediately and loudly. Frankly, inaccurate API documentation is a plague on our industry, responsible for unknown thousands of hours of lost productivity, and we should encourage solving that problem by constantly validating parity between server code, client code, and API specification.

I’ve done things to solve this before by adding an option to my server-side code to validate all inputs and outputs against an API schema (I never got around to validating the endpoints themselves, but that’s also a very important thing to check). This flag would be enabled for all unit tests and when the server was being run in a development mode. This flag would cause any mismatch with the schema to immediately raise an exception.

When not running with the flag, validation would still happen, but mismatches would only cause a message to be logged instead of an actual failure.

Now, I can imagine two systems: editing the RAML by hand whenever new features or changes are being developed for my API, or auto-generating the RAML based on annotations in my source code. I’m really happy with either case, as long as the aforementioned validation is happening :slight_smile: