Right way to create a 'filter' parameter


#1

Hi,
I have a filter parameter for an endpoint, here is how it is defined:

  /products:
    displayName: Products
    get:
      displayName: List products
      queryParameters:
        filter[<field>]:
          type: string[]
          required: false
          description: |
            A `field=value` pair defining the filter applied to the response.
          examples:
            first:
              value: ['filter[color]=Black']
              description: "Lookup for products with color black."
            second:
              value: ['filter[color]=Black','filter[color]=White']
              description: "Lookup for products with color black or white."
...

My issue with this is that it does not seem right to mention the parameter name again in the example.

In a simpler situation we would have:

    get:
      displayName: Get product 
      queryParameters:
        product_id:
          required: true
          description: |
            The identifier of the product.
          type: string[]
          example: ['111','123']

This is nice, and I can generate HTML output something like ?product_id=111&product_id=123

So is there a way to use the specs properly to represent a filter that can be used on any field name and exemplify this?

Thanks for your insight.


#2

Have you looked into ResourceTypes and Traits? A trait, say “filterable”, could be applied to any resource that can be filtered, and the name of the field could be passed to that trait as a <<parameter>>.