Back end behaviors - where to describe/specifiy?


Hello, please go easy on me as it’s my first time writing a RAML spec and also posting in this forum.

RAML is obviously very good at describing the inputs and outputs of an API.

How about describing (or in my case specifying to implementers) how to get from the in to the out, i.e. details of the back-end behaviors that will produce the correct expected output?

Is there a more structured place to put back end business rules like which indexes to search when handling a query request than just in one of the description: attributes and/or documentation: files?


I am also very interested in this question. For my use case, ideally a RAML document should contain all the information about the API, and the tools in the ecosystem should be able to export that to different formats and for different purposes. Today I see other groups in my industry distributing non-REST APIs using tools like Altova XML Spy to specify XML XSD and JSON schemas, together with Word/PDF documentation.

When I compare the documentation we obtain from RAML+Tools vs Altova+Word/PDF I see that RAML is much richer for API definition and it is incredible flexible, but the output is so poor it looks like a hobbyist tool. Obviously my expectations are very high considering the amount of money that has been invested in Altova and Word, they have been around forever and their feature set is very extensive.

We have been contacted by a group of European companies to convert legacy TCP APIs to REST APIs, and maybe in a next phase design an API certification program. The discussions have been around RAML because we are invested in RAML and some of its tools. However this is the big leagues now and we are not totally convinced this is the right path, so we have assigned one of our team members to search for alternatives.

Do I really have to fall back to Word and generate documentation manually? It would probable double or triple our effort… Are my expectations realistic? Will we be able to generate decent documentation and schemas from a RAML project or am I dreaming? I don’t mind paying a subscription. Hello Mulesoft, how about a solution for Enterprise users?

So back to the OP subject, what would be the correct way to document backend behaviour? Should we just use description and write 500 word essays on how the backend behaves? How would that show up in the resulting documentation? I can’t imagine RAML2HTML creating anything really useful since it can’t even describe a string array properly or use the width of the screen without wrapping examples horribly until they are no longer readable.


You guys are hitting on exactly what RAML CAN do… but is not yet quite capable of. Let me explain my vision… at least what I know is possible but not yet implemented. The beauty of RAML 1.0 besides the RAML Types (which has the potential to replace JSON Schema in my opinion), is the annotation framework. The unfortunate problem of the annotation concept with RAML is that it is completely left to each and every RAML parser/generator to implement… and as such is difficult at best to say USE THIS because you dont know who is going to support your dynamic annotations. You can certainly provide robust documentation by using Markdown and including links to it in your RAML… but let me jump to my biggest problem with Swagger UI and RAML2HTML. They both merely show you a list of endpoints and what each does… in their own respective layouts. I personally dislike Swagger UI… it lists every endpoint in a flat list of endpoints that you can expand, try, etc. Same with RAML2HTML but it is more organized by grouping the GET/PUT/POST/etc into a tree structure. Still… you have NO IDEA how to use the API just by looking at it. It is merely a way to understand a specific endpoint. You can try any endpoint…but some endpoints require data as part of the request… how do you know what API to call to get the data needed? That information is lacking in current API designs.

So… how do you USE the API? That information is lacking and today the only way to really know how is either via documentation that is written by hand, manually, typically a doc writer that is part of the API design team and knows how the API would be used would write a programmers guide to explain it. Or… my favorite option is writing Postman collections, again manually, that show how to use the API via a collection “workflow”. It is easy to do, pretty fast for the most part… BUT… the stickler is… you STILL have to take advantage of Postmans own request/response parsing capability… that is to say, you have to know that a given API call returns a response, and then add some javascript code to that Postman request that parses the response, and sets some collection variables. Then, the next request in the Postman chain uses those previously set variables in its request (e.g. the URL line, the headers, or even in a body if it were say a POST/PATCH/PUT call). This works really well, and frankly I much prefer publishing a Postman collection on how to string together various API endpoints to do something useful. Unless your API is single call capable… e.g. get me a stock price from this one endpoint for this stock name… you are most likely building a UI or automation workflow via your API that requires more than one call, and worse… the call chain has to be in a specific order, often pulling from a previous calls response values to make the next call.

So… that is where annotations come in to play for me. It would not be difficult to define a few annotations that indicate WHAT API endpoint must be called BEFORE this endpoint can be called… and WHAT response data from that call must be available before this request can be called. With that data information, you can actually auto generate Postman collections, complete automated tests, etc. It is completely possible to do this today with RAML 1.0 (but not Swagger or RAML 0.8… or at least without a huge amount of work and secondary files). The only thing holding this back… what tool utilizes the defined annotations to provide this info? If RAML2HTML is the defacto standard way we generate API documentation from RAML, and RAML2JAXRS is the defacto way we generate JAXRS server side code from RAML… how will they take advantage of these new custom annotations to generate better documentation, code, etc? There inlies the problem. They wont. Or at least… they probably wont. You have to get EVERY project/team/developer on board with a set of “standard like” annotations that they all agree to, or at least agree to providing support for those annotations.

The question has been raised before…why are there not a set of annotations the RAML 1.0 spec defines and requires support of? I have asked that too. I think the main reason is… the spec is beyond good enough to define API endpoints, in fantastic detail… enough that you can provide good API endpoint documentation, good code generators to build SDKs, CLIs, etc with. BUT… there is NO WAY the SPEC designers could possibly know how any given API will be used, so I think the choice to leave annotations as a custom option makes good sense.

To that end, what I have pitched to @christian_vogel and he has told me to figure something out (so maybe this is a good way to lead in to that) is to put together some sort of central set of annotations that we as a group define… not only writing the actual .raml file with them defined, but documentation on what they mean, how they should be used, etc. I have proposed the idea on the site that we have a menu option or something that says Annotations or whatever, and on that page, we define/list them, and as well, list the different projects that support custom annotations. Id also like to see individual projects have something show up on that say Annotations support (a link) and a popup/etc of the annotations it supports. I think it is a very good step towards what the OP and myself and others would like to see… how to define a way in the RAML API definition of using the API endpoints.

The biggest problem with the above approach will be projects supporting different annotations. So now, if RAML2HTML only supports say a couple, but not all… then we need yet another doc generator tool to add support for the rest… but then you are using 2 tools or 3 or 4 to get your docs generated with all the support you want… or we are having multiple different doc generators, each with their own way of generating doc layout/details… so now someone may love RAML2HTML output, and not like the other format… but wants the annotation support the other format has.

Hopefully what this will foster is more developers in the community joining up to add support for annotations (assuming we get that in place first) for given projects!!

So… lot to say… what do you think?


Interesting comments - thanks so much for sharing these detailed background considerations.

I would be very interested in some kind of XML output. I’m using oXygen so it would be ideal if we could take advantage of the full DITA (and now markdown!) support…


BTW, I have started this repository as a central place to collect annotations for now. Feel free to contribute.


The question has been raised before…why are there not a set of annotations the RAML 1.0 spec defines and requires support of?

As for me annotations are the extensions to standard. Using the Java analogy annotation types are part of the Java language, but none of particular annotations is a part of Jave specification itself(use we have few in standard library but this is a bit different beast).

There is an enourmous set of potential annotations which you might want to introduce for different usecases, and it is pretty hard to reason about them before you have or actually writing tools which actually use them. So as for me it does not look possible to use revolutionary approach to this(few person sit together and create set of annotations from their brilliant or not to brilliant minds).

So as for me this standard sets of annotations/datatypes should be born by evolution, which might be facilitated and directed by having a right process and approach to it. Continuing analogy with Java: it has a JCP which allows different vendors to talk and agree about standard APIs and annotations for differnet use cases.

The biggest problem with the above approach will be projects supporting different annotations.

Initially yes, but this is probably ok, at some moment when critical mass will be reached they should start converging. We just need a place and clear process for doing it.

You guys are hitting on exactly what RAML CAN do… but is not yet quite capable of. Let me explain my vision… at least what I know is possible but not yet implemented.

As for me the biggest problem here is that infratstructure is still not quite done :-(. When it will become more mature and more projects will evolve it, it will be much more easy to reason about annotations that we need.

Hopefully what this will foster is more developers in the community joining up to add support for annotations (assuming we get that in place first) for given projects!!

I am completely with you on it and publishing my libraries of annotations on consistent basis in the registry which I am trying to build.


BTW, I have started this repository1 as a central place to collect annotations for now. Feel free to contribute.

The problem is that there is no process around it, so there is no reasons to use it at this moment.


@mhGLEIF do you have any particular examples of behaviors which you would like to document?

@rojocapo, is it possible to ask you about some more detailed feature requests or examples of what you miss in current tools? (Lets imagine that obvios bugs are fixed)



Can you elaborate on what you mean by that?


Hi @christian_vogel,

Let me try to explain my position by example:

At this moment my Swagger<->RAML library generates few annotations, that represents some aspects of swagger specifications which are not supported by RAML natively, currently I support them in the RAML specifications renderer which I am developing, and plan to support them in other tools that I might build.

Let’s now imagine that I am contributing them to the repository. At first I need to pass through review process (which is a pretty big unknown, especially considering what happened with my PR to RAML for JAXRS).

Okey, lets assume that this is done, how it would help myself and another tool makers. At first at this moment we do not have any community of tool makers (and this is pretty sad actually), so most likely no body will see it, or struggling with a more critical things.

Secondary after passing it, I need to support the thing which I can not affect (let’s imagine that a month after review another PR which changes the library which I contributed and using/supporting in my tools dramatically, was accepted).

So at this moment contribution to this repo means:

  • Spending a lot of energy on the thing which will most likely be ignored by everybody(and even worse most likely will be ignore because they do not know that it exists)
  • Introducing dependency on something that may unpredictably change in a moment indepently from me, and that I need to support after contribution.
  • It might be that I will get some useful comments and insights from discussions around PR, but to achieve this repo should be more visible.

Building healthy ecosystem for a language/platform is a complex task. Annotations/Libraries is a precious element which makes it is much easier, but there is another not technical element which is a necessary to make it useful for tool makers (and as for me tool makers are key element for a language success) - clear and predictable process for collaboration.

In an ideal world I would like to see a process similar to something similar to JCP process, or Eclipse Development Process

but being a little bit more realistic ad for me there are following key elements that process should have

  • Vendor neutrality
  • Simple and formal acceptance criterias
  • Visibility
  • Expert groups and clear governance for each topic.(tool makers which are interested in building tools)
  • Clear connection of libraries with the tools which claim to support them.

What do you think?



@pavel you make some great observations and comments. My point of the central annotation repo is exactly what you said… a JCP like set of people, in this case maybe me, you, @christian_vogel and a few more, can review/discuss via email or in the forum thread itself. At some point, I would hope for an agreement of all (or most) parties, especially the ones contributing the annotation/definition. Given how the RAML 1.0 spec went, it is completely possible. I suspect annotations wont take over a year to agree upon though, as they of course arent nearly as large or complex as the RAML spec.

I would argue though that the central repo that @christian_vogel started is a fine place for annotation .raml files to end up. There is the ability to discuss it there, and changes can be made/reviewed/committed for others to use.


Okey guys, lets try to work on it together, I have created initial PR with a library describing mapping of RAML types to Java it definitely needs more work, but as for me it might be a good start for conversation. I know at least 3 implementations of it (my, scraml, and the one which is developed by guys who work on raml4jaxrs project now), so it looks like something that already may benefit from standartization on other side it does not moves us into to complex issues associated with more complex/general libraries.



Thanks Pavel. I made my comments already. Do you think I should ask JP who works on the raml4jaxrs to review as well?


Yes sure. I do not expect that it will be a quick process, but it should be easier to agree on this then on something more conceptual.