Support for tagging based API resource filtering


#1

Hello,

We have a set of API’s developed using RAML defenition and is available in the API portal as reference .
Everything looks fine except we are not finding a good categorization feature for API to be grouped under a specific section\tag. This tag based categorization and rendering is observed in swagger console.
Many of our tenant’s who were new as well as experienced with swagger before felt the same and mentioned that API reference is not cool enough due to the lack of tagging capability.

To explain in detail about our expectation , PFB the sample .

Below are the API’s we have developed and the API reference will show something similar to the one shown below:

/mycompany/org/employee - All Employees under Org :get :post :put /mycompany/org/{busid}/employee – All Employess under a Business Unit :get /mycompany/{personnelid} – Get and Update Employees/Contractors in the Org :get :put /mycompany/org/contractor - All Contractors under Org :get :post :put /mycompany/org/{busid}/contractor – All Contracts under a Biz :get

Expectation is to see the below Tag Hierarchy to enable filtering based on Context.

Organization -------Employees -------Contractors Employees Contractors

The above resources will be tagged as below:

/mycompany/org/employee - All Employees under Org :get Tags: Organization Employees Employees :post Tags: Organization Employees Employees :put Tags: Organization Employees Employees /mycompany/org/{busid}/employee – All Employess under a Business Unit :get Tags: Employees /mycompany/{personnelid} – Get and Update Employees/Contractors in the Org :get Tags: Organization Employees Contractors Contractors Employees :put /mycompany/org/contractor - All Contractors under Org :get Tags: Organization Contractors Contractors :post :put /mycompany/org/{busid}/contractor – All Contracts under a Biz :get

This captures the UX/UI aspect of the above tagging.

Step 1: The Console will understand these tags and render like below with all the resources. First default view will not filter, but show the First level tags.

Tags Filter: ORGANIZATION EMPLOYEES CONTRACTORS

<<All the resources for the API>>

Step 2: Clicking on any of the tags will filter for resources which have the above Tag at the first level. So in the above case clicking on Organization would’ve shown the below resources along with the Second Level Tag for further filtering.

Tags Filter: EMPLOYEES CONTRACTORS

/mycompany/org/employee - All Employees under Org :get :post :put /mycompany/{personnelid} – Get and Update Employees/Contractors in the Org :get :put /mycompany/org/contractor - All Contractors under Org :get

Step 3: Clicking on EMPLOYEES will render as below:

Tags Filter: Empty – because there are no more tags at third level

/mycompany/org/employee - All Employees under Org :get :post :put /mycompany/{personnelid} – Get and Update Employees/Contractors in the Org :get
Note: In the examples, we have consciously not shown resources that didn’t have any Tags.

Regards
Arun


#2

Hi @arubalac, thanks for your post. So what is that about? Is this feedback? Is it about RAML or tooling? :slightly_smiling:


#3

Hi @christian_vogel,

This is a enhancement which we and our tenants like to see on RAML based tooling (API designer \ Atom etc) and need not impact the RAML spec.

The core reason for this requirement is that the UI experience of API reference is not as comfortable as the one provided in the swagger where the API can be categorized like a folder with some context or business name. In API reference there is no such feature and the structure is flat and straight with no category \ grouping .

We believe that above feature can be achieved by the changes on RAML based tooling and piggybacking on the annotation features on RAML spec.

++ @dirosden

Regards
Arun


#4

It would be great to have some think like swagger tags
eg:

paths:
    /projects:
        get:
            operationId: listProjects
            tags:
                - project
            summary: List the projects

it helps code generation tools to generate more de-composited code
this tool uses tags very pretty https://github.com/go-swagger/go-swagger


#5

I think it’s a great idea and as @arubalac highlighted, maybe not something we need to directly put in the spec for now. RAML annotations should give you a good starting point. For example:

annotationTypes:
  tags: string[]

/projects:
  get:
    (tags):
      - project

Now, a code-gen could take that and does what ever it needs to do. I know that annotations are not something very official, but we are working in parallel on a RAML annotations repository that people can refer to. And of course, at some point - annotations can go into the specification.

What I would suggest in any case, look if there is any issue about that in the specification repo already; if not simply create one so that we can keep track.