Roles to be defined at method level


#1

I am doing RAMLification of my APIs. My APIs are designed to used based on the roles. Like some APIs are accessible for End USer, some oare to Administrators and some to SuperUser.
How can i define these Roles in RAML?

Thanks
Keshav


#2

As for now, RAML does not have OOTB properties to define roles on any level. What you could use though is a set of annotation that either defines role-based on a specific API or on deeper levels such as resource or methods.


#3

Thanks Christian.
Right now with RAML 1.0 i don;t find any tool to publish document. raml2html support only 0.8. API Workbench support 1.0 but i can’t generate documentation from this for publishing purpose. Cna you please suggest how to go about it?

Thanks
keshav


#4

I know that @Mike_Stowe is working on the support for RAML 1.0 (RC) in raml2html, and MuleSoft does the same for the API Console. There is still some small steps left to finalise the specification as the RAML Workgroup got tremendous feedback that needs to be incorporated. Therefore, the development of these tools is much slower at this stage I am afraid.

Please bear with everyone :wink:


#5

I had a similar question. We have different properties available depending on what role you have. For example if it returned a person, maybe some people get First Name, Last Name and SSN. But if you don’t have the right permissions then you only see First Name and Last Name. When I try to use annotations it seems like it doesn’t apply on the property level. Any idea on the best way to be able to document this? I’m using 1.0


#6

By not having ROLES in your specification, their is a discrepancy in the DATA associated with the endpoints. TOKENS send ROLES associated with endpoints that can be checked but you don’t provide a way by not providing that data. And by not associating that data, there is not way to synchronize that data. So the RAML spec is incomplete without security.


#7

Can you elaborate a little bit more on your case, please? Maybe using an example on how that should look lke in RAML.


#8

Here is a gist of an object I created an use https://gist.github.com/orubel/159e94db62023c78a07ebe6d86633763

If you scroll down in the gist, you can see stuff like:

            "list":{
             	"METHOD":"GET",
            	"DESCRIPTION":"List Hook",
            	"ROLES":["ROLE_ADMIN","ROLE_ARCH"],
            	"BATCH":["ROLE_ADMIN","ROLE_ARCH"],
                "REQUEST": {
                    "permitAll":[]
                },
                "RESPONSE": {
                	"permitAll":["id","version","user","name","url","format","service"]
                }
            },

This is one file that I use at the api server that I can syncronized and PUSH to all subscribing services (like the API Gateway or the MQ) so that all services in the architecture stay in sync and have the EXACT SAME data at all times.
‘permitAll’ implies ALL roles have to send (or get returned) that data and you can make it more atomic by adding additional ROLE requirements.

I have talked about this at APIWorld, RestFest, SpringOne, etc. Here’s a video from a recent talk… https://vimeo.com/236606539

And here’s a Redhat article on it… https://developers.redhat.com/blog/2017/10/12/new-api-pattern/